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Preface 


Intended Audience 


This manual is for programmers at all levels of experience. It covers both user 
interfaces of the debugger: 


¢ The VMS DECwindows interface, for workstations 
¢ The command interface, for terminals and workstations 


The debugger can be used with most VAX languages. This manual emphasizes 
usage that is common to all or most languages. For additional information 
that is specific to a particular language, see Appendix E and the documentation 
furnished with that language. 


Note that you can use the VMS Debugger only to debug code in user mode. You 
cannot debug any code in supervisor, executive, or kernel modes. If you need 
to debug code in other than user mode, refer to the VMS Delta /XDelia Utility 
Manual. 


Document Structure 


This manual is organized in two parts: 


¢ Part I introduces the debugger’s DECwindows interface. Additional 
information about the DECwindows interface is available through online 
help, as explained in Chapter 1. 


¢ Part II completely describes the debugger’s command interface: 
— Chapter 2 introduces the command interface. 


— The remaining chapters provide task-oriented and conceptual information. 
To simplify the discussions, many details about the debugger commands 
are not included in these chapters. 


— The command dictionary provides complete reference information about 
all debugger commands. 


— The appendixes provide reference details about specific subjects. 


Associated Documents 


General information about the VMS DECwindows interface is available in the 
VMS DECwindows User’s Guide. 


Information about compiling and debugging that is specific to a particular 
language is available in the documentation furnished with that language and in 
Appendix E of this manual. 


Information about VAX assembly-language instructions and the VAX MACRO 
assembler is available in the VAX MACRO and Instruction Set Reference Manual. 


xix 


Information about the linking of programs and about shareable images is 
available in the VMS Linker Utility Manual. 


Conventions 


The following conventions are used in this manual: 


mouse 


MB1, MB2, MB3 
Ctrl/x 


PF1 x 


() 


{} 


red ink 


numbers 


XX 


The term mouse refers to any pointing device, such as a 
mouse, puck, or stylus. 


MB1 indicates the left mouse button, MB2 indicates the 
middle mouse button, and MB3 indicates the right mouse 
button. (The buttons can be redefined by the user.) 


A sequence such as Ctrl/x indicates that you must hold down 
the Ctrl key while you press another key or a pointing device 
button. 


A sequence such as PF 1 x indicates that you must first press 
and release the PF1 key and then press and release another 
key or a pointing device button. 


In examples, a key name is enclosed in a box to indicate that 
you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


In examples, a horizontal ellipsis indicates one of the 
following possibilities: 


e Additional optional arguments in a statement have been 
omitted. 


e The preceding item or items can be repeated one or more 
times. 


e Additional parameters, values, or other information can 
be entered. 


A vertical ellipsis indicates an omission in a code example 
because the omitted items are not important to the topic 
being discussed. 


In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices in 
parentheses. 


In format descriptions, brackets indicate that whatever is 
enclosed within the brackets is optional; you can select none, 
one, or all of the choices. (Brackets are not, however, optional 
in the syntax of a directory name in a file specification or 

in the syntax of a substring specification in an assignment 
statement.) 


In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 


Red ink indicates information that you must enter from the 
keyboard or a screen object that you must choose or click on. 


For online versions of the book, user input is shown in bold. 


‘Unless otherwise noted, all numbers in the text are assumed 


to be decimal. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 


Part I 


Using the Debugger: DECwindows Interface 


This part introduces the VMS debugger’s DECwindows interface. Additional — 
information about the DECwindows interface is available through online help. 


For information about the debugger’s command interface, see Part IT. 
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Introduction to the Debugger: DECwindows 
Interface 


This chapter introduces the VMS debugger’s DECwindows interface and provides 
enough information to get you started. For information about the debugger’s 
command interface, see Part II of this manual, which starts with Chapter 2. 


The following information is provided in this chapter: 
e An overview of the debugger’s main features 


¢ Instructions to prepare your program for debugging and start a debugging 
session 


e An overview of the debugger windows and menus 
e A sample session to get you started with the debugger 
¢ Introductions to most of the functions you can perform with the debugger. 


Many topics are covered very briefly. The documentation for the debugger’s 
DECwindows interface consists mainly of online help, and this chapter includes 
numerous references to specific topics in the debugger’s Help menu, in the main 
window. The debugger’s online help system is explained in Section 1.5.1. 


To use this chapter most effectively, read it while running the debugger on your 
workstation. 


It is assumed that you are familiar with the general DECwindows environment 
as described in the VMS DECwindows User’s Guide—that is, you should know 
how to use the pointer and keyboard to manipulate‘windows, menus, dialog 
boxes, online help, and so on. 


If you are already familiar with the debugger’s command interface, including how 
to invoke the debugger from DCL level (as described in Part II of this manual), 
you can start with Section 1.2.3. 


1.1 Overview of the Debugger 


The debugger is a tool that helps you locate run-time programming or logic 
errors, also known as bugs. You use the debugger with a program that has 
been compiled and linked successfully but does not run correctly. For example, 
the program might give incorrect output, go into an infinite loop, or terminate 
prematurely. 


You locate errors with the debugger by observing and manipulating your program 
interactively as it executes. The debugger enables you to do the following tasks: 


¢ Control the program’s execution—start the program, stop at points of interest, 
resume execution, and so on 


e¢ Trace the execution path of the program 
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¢ Monitor changes in variables and other program entities 
¢ Monitor exception conditions and language-specific events 
e Examine and modify the values of variables, or force events to occur 


¢ In some cases, test the effect of modifications without having to edit the 
source code, recompile, and relink 


These are the basic debugging techniques. After you are satisfied that you have 
found the error in the program, you can edit the source code and compile, link, 
and execute the corrected version. 


As you use the debugger and its documentation (particularly the online help), you 
will discover variations on the basic techniques. You can also tailor the debugger 
for your own needs. 


The debugger is a symbolic debugger. You can specify variable names, routine 
names, and so on, precisely as they appear in your source code. You do not 
need to specify memory addresses or VAX registers when referring to program 
locations, although you can, if you want. 


You can use the debugger with the following VAX languages: 


Ada 
BASIC 
BLISS 


Cc 
COBOL 
DIBOL 

- FORTRAN 
MACRO-32 
Pascal 
PL/I 
RPG II 
SCAN 


The debugger recognizes the syntax, data typing, operators, expressions, scoping 
rules, and other constructs of a given language. If your program is written 

in more than one language, you can change the debugging context from one 
language to another during a debugging session. 


1.2 Starting a Debugging Session 


The usual way to invoke the debugger from a DECterm window is as follows: 
1. Compile and link the program with the (DEBUG command qualifier. 


2. Make sure that the debugging configuration (default or multiprocess) is 
appropriate for the kind of program you are going to debug. 


3. Invoke the debugger by entering the DCL command RUN. 


These steps are explained in the following sections. Additional options for 
invoking the debugger are discussed in Section 1.6. 
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1.2.1 Compiling and Linking a Program to Prepare for Debugging 


Before you can use the debugger, you must compile and link the modules 
(compilation units) of your program as explained in this section. The following 
example shows how to compile and link a Pascal program, consisting of a single 
compilation unit named EIGHTQUEENS, before using the debugger. 


Note 


The /DEBUG and /NOOPTIMIZE qualifiers are compiler command 
defaults for some languages. These qualifiers are used in the example for 
emphasis. 


$ PASCAL/DEBUG/NOOPTIMIZE EIGHTOQUEENS 
$ LINK/DEBUG EIGHTQUEENS 


The /DEBUG qualifier on the compiler command (PASCAL in this case) directs 
the compiler to write the symbol information associated with EIGHTQUEENS . 
into the object module, EIGHTQUEENS.OBJ, in addition to the code and data for 
the program. This symbol information enables you to use the names of variables 
and other symbols declared in EIGHTQUEENS in debugger dialog boxes and 
commands. If your program has several compilation units, you must compile each 
unit whose symbols you want to reference with the /DEBUG qualifier. 


Some compilers optimize the object code to reduce the size of the program or 

to make it run faster. In such cases you should compile your program with the 
/NOOPTIMIZE command qualifier (or equivalent) when preparing for debugging. 
Otherwise, the contents of some program locations might be inconsistent with 
what you would expect from viewing the source code. (After the program has 
been debugged, you will probably want to recompile it without the /NOOPTIMIZE 
qualifier to take advantage of optimization.) 


The /DEBUG qualifier on the LINK command directs the linker to include all 
symbol information that is contained in EIGHTQUEENS.OBJ in the executable 
image. The qualifier also causes the VMS image activator to start the debugger 
at run time. If your program has several object modules, you need to specify 
those modules in the LINK command, for most languages. 


1.2.2 Establishing the Debugging Configuration 


Before invoking the debugger as explained in Section 1.2.3, check that the 
debugging configuration is appropriate for the kind of program you are going to 
debug. 


You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or several 
processes, respectively. The configuration depends on the current definition of 
the logical name DBG$PROCESS. Thus, before invoking the debugger, enter the 
DCL command SHOW LOGICAL DBG$PROCESS to determine the definition of 
DBG$PROCESS. 


Most of this chapter covers programs that run in only one process. For such 
programs, DBG$PROCESS either should be undefined, as in the following 
example, or should have the value DEFAULT: 


$ SHOW LOGICAL DBGSPROCESS 
$SHOW-S-NOTRAN, no translation for logical name DBGSPROCESS 
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If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 


$ DEFINE DBGSPROCESS DEFAULT 


For more information about multiprocess debugging, see Section 1.5.16. 


1.2.3 Invoking the Debugger 


1-4 


After you compile and link your program and establish the appropriate debugging 
configuration, you can then invoke the debugger. To do so, enter the DCL 
command RUN, specifying the executable image of your program as the 
parameter. For example, enter the following command to debug the program 
EIGHTQUEENS: 


$ RUN EIGHTQUEENS 


By default, the debugger comes up in the following three windows, arranged as 
shown in Figure 1-1: 


e The main window. 


¢ The predefined source window SRC, which shows the source code of the 
module you are debugging. The numbers shown at the left of the source code 
are compiler-generated line numbers, as they might appear in a compiler- 
generated listing file. 


¢ The predefined output window OUT, which displays the debugger’s output. 
For example, it shows the value of a variable that you are examining. 
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Figure 1-1 Debugger Windows at Startup 


Me Vi AX DEBUG: Copyright «i Digital Equipment Corporation. 1989. | all Rights Reserv red 


Eile Edit Control Data Customize 
We) Current Entity: [[(no current entity) 


(yd) Call Frame: (| (EIGHTQUEENS) 
Visible Process: [11 ( JONES_TWA4) 


Wal VAX DEBUG: SRC- module EIGHTQUEENS 2351 
File Edit Commands 
:_ PROGRAM Eightqueens (OUTPUT 


: INTEGER; 

: ARRAY[1..8] OF BOOLEAN; 

: ARRAY[2..16] OF BOOLEAN; 

: ARRAY[-7..7] OF BOOLEAN; 

: ARRAY[1..8] OF INTEGER; 
afe : BOOLEAN; K: INTEGER; 


PROCEDURE Print; 
BEGIN (4 Print *) 


ead) = 2AM Me = eal eh a ea 


%DEBUG-I-INITIAL, language is PASCAL, module set to EIGHTQUEENS 
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Windows SRC and OUT are two examples of the kinds of debugger windows you 
can use to capture and display different types of data. 


The message that is displayed in window OUT at debugger startup indicates 
that this debugging session is initialized for a Pascal program and that the name 
of the main program unit (the module containing the image transfer address) 

is EIGHTQUEENS. The initialization sets up language-dependent debugger 
parameters. 


By default, the boxed line in window SRC indicates where execution is currently 
suspended. When you start a debugging session, the debugger usually suspends 
execution at the beginning of the main program (line 1, in this example). For Ada 
programs and certain other kinds of programs, execution is initially suspended 
at the beginning of initialization code, before the main program, so that you can 
choose to execute that code under debugger control. To execute to the beginning 
of the main program in such cases, click on the Go button in the main window. 
See your language documentation for more information. 


You can now use the debugger to start execution, set breakpoints, examine 
variables, and so on, as explained in Section 1.4 and Section 1.5. Section 1.3 gives 
an overview of the debugger’s windows and menus. 
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1.3 Debugger Windows and Menus 


The debugger windows consist of a main window and several predefined windows 
that capture and display different kinds of data. The following sections briefly 
describe these windows and the pop-up menu, which is available from any 
debugger window. 


For more information, choose Overview from the Help menu, then choose 
Debugger Windows and Menus. 


1.3.1 Debugger Main Window 


The debugger’s main window (see Figure 1-2) includes a menu bar, a status 
region, and four buttons that are labeled Go, Step, Examine, and Stop. 


_ Figure 1-2 Debugger Main Window 


a VAX DEBUG: Copyright © Digital Equipment Corporation. 1989. All Rights Reserved (a Fil} 


File Edit Contro! Data Customize Help ] 


Oe) Current Entity: lI(no current entity) 


(OIL) Call Frame: 0] (EIGHTQUEENS) 
Visible Process: | (JONES_TWA4) 
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e Figure 1-3 shows the menus on the main window’s menu bar. Figure 1-4 
and Figure 1-5 show the submenus of the Data and Customize menus, 
respectively. Table 1-1 summarizes the functions of these menus and 
submenus. 


¢ Table 1-2 summarizes the type of information displayed in the status region 
fields and the functions of the associated arrow buttons. 


¢ Table 1-3 summarizes the functions of the Go, Step, Examine, and Stop 
buttons. 


Note that the functions of the Go, Step, and Examine buttons can also be - 
performed through other means, such as the pop-up menu, Control menu, or 
Data menu. 
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Figure 1-3 Main Window Pull-Down Menus 
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Figure 1-4 Data Menu and Submenus 
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Figure 1-5 Customize Menu and Submenus 
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Main Window Pull-Down Menus 


Description 


End the debugging session. 


Copy text to the clipboard, or paste text from the clipboard to a debugger 
dialog box or the COMMAND box. 


Start, stop, and monitor the execution of your program under debugger 
control. For example: execute to the next line or to the next VAX 
assembly-language instruction; set breakpoints, tracepoints, and 
watchpoints; call a routine. For vectorized programs, force synchronization 
between the scalar and vector processors. 


Display or manipulate data that is associated with your program. For 
example: examine variables and arbitrary program locations; assign 
new values to variables; evaluate language expressions; control access 
to variable names, routine names, and other symbols; manipulate 
multiprocess programs and tasking (multithread) programs. Note that 
the Tasks menu item is dimmed unless you are debugging a VAX Ada 
program or a program written in any language that uses DECthreads 
tasking services. 


Tailor your debugging environment and establish default conditions. 
For example: create and manipulate debugger windows; change the 
programming language context; establish defaults for manipulating 
data and for accessing symbols; open the COMMAND box to access the 
debugger’s command interface. 


Obtain conceptual and task-oriented information about the debugger. This 
is an alternative to obtaining context-sensitive help on individual items 
that are displayed on the screen (menus, buttons, dialog boxes, and so on). 
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Table 1-2 Main Window Status Region 
Label Description 


Current Entity Identifies the last entity that was examined or whose value was 
changed (for example, a variable or a code location). Use the 
arrow buttons to display consecutive logical entities—for example, 
consecutive elements of an array variable. 


Call Frame Identifies the routine that the debugger uses as reference when 
displaying source code in the source window or instructions in 
the instruction window, or when searching for symbols that are 
associated with your program (variable names, routine names, and 
so on). Use the arrow buttons to reset the reference to another call 
frame on the call stack. 


Visible Process For a one-process program, identifies the process that is running 
the program. For a multiprocess program, identifies the process 
that is currently the context for entering process-specific commands. 
Use the arrow buttons to reset the visible process to another process 
that is under debugger control. 


Table 1-3 Main Window Buttons 


Button Description 
Go Start execution from the current program location. 
Step Execute the program one step unit of execution. By default, this is one 


executable line of source code. 


Examine Display the value of a variable or other entity whose name is selected in a 
window, or the value of the entity last examined, if no text was selected. 


Stop Interrupt program execution or a debugger operation without ending the 
debugging session. 


1.3.2 Debugger Predefined Windows 


The debugger provides the following predefined windows that you can use to 
capture and display different kinds of data: 


SRC, the predefined source window 

OUT, the predefined output window 

AUTO, the predefined automatic window (a special output window) 
INST, the predefined instruction window 

REG, the predefined register window 


Of these windows, only SRC and OUT are displayed, by default, at debugger 
startup. 


The basic features of the predefined windows are described in the next sections. 
You can change certain characteristics of these windows, such as buffer size 

or window attributes. You can also create additional windows similar to the 
predefined windows. For more information, choose Overview from the Help menu, 
then choose Debugger Windows and Menus, then choose Debugger Predefined 
Windows (SRC, OUT, INST, REG, AUTO). 
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1.3.2.1 Predefined Source Window (SRC) 


You can use window SRC to display source code in two basic ways: 


¢ By default, SRC automatically displays the source code for the module 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 


¢ In addition, you can use SRC to display the source code for any part of your 
program. 


The name of the module whose source code is displayed is shown at the right 
of the window name, SRC. The numbers displayed at the left of the source code 
are the compiler-generated line numbers, as they might appear in a compiler- 
generated listing file. 


The next paragraphs describe the behavior of SRC when it is displaying the 
current location. Section 1.5.5 explains how to display source code in arbitrary 
locations. 


As you execute the program under debugger control, window SRC is updated 
automatically whenever execution is suspended. The boxed line indicates the 
next line to be executed. 


If the debugger cannot locate source lines for the routine in which execution is 
suspended (because, for example, the routine is a run-time library routine), it 
tries to display source lines in the next routine down on the call stack for which 
source lines are available. If the debugger can display source lines for such a 
routine, it issues the following message: 


$DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 
Displaying source in a caller of the current routine. 


In such cases, the boxed line in the source window identifies the line to which 
execution returns after the routine call. Depending on the source language and 
coding style, this might be the line that contains the call statement or the next 
line. 


If your program was optimized during compilation, the source code displayed in 
window SRC might not always represent the code that is actually executing. The 
predefined instruction window INST is useful in such cases, because it shows the 
exact VAX instructions that are executing. See Section 1.3.2.4. 


1.3.2.2 Predefined Output Window (OUT) 
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Window OUT is a general purpose output window. By default, it displays the 
following information: 


e Any debugger output that is not directed to windows SRC, INST, or AUTO. 
For example, if window INST is not displayed or does not have the instruction 
attribute, any output that would otherwise update window INST is displayed 
in window OUT. 


¢ Debugger diagnostic messages. Messages with a severity level greater than I 
(informational) are also displayed in a message box (see Section 1.5.2). 


Note that, when displaying variable names, routine names, and other symbolic 
address expressions, the debugger adds a path name prefix to the name. The 
path name prefix identifies the nesting program elements in which the entity was 
declared in the program. For example, if you examined a variable K, whose value 
was 26, in routine SWAP of module SWAP_PACK, the debugger might display the 
following output: 
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SWAP_PACK\SWAP\K: 26 
In this case, SWAP_PACK\ SWAP\ is the path name prefix. 


In most cases, you do not need to include a path name prefix when specifying 
symbolic address expressions (see Section 1.5.10.2). 


1.3.2.3 Predefined Automatic Window (AUTO) 
Window AUTO is an automatically updating window that can be used instead 


of window OUT to display the output from the following dialog boxes, which are 
accessible from the Data menu: 


Examine Variable 
Examine Address or Register 
Language Expressions 


Window AUTO is created when you first click on the Display button in any one of 
these dialog boxes. Thereafter, AUTO remains open until you close it. 


AUTO includes a debugger command list in its definition. Every time the 
debugger gains control, AUTO is updated with the output of that command 
list. 


When AUTO is created, its command list consists of the Examine or Evaluate 
command that was generated when you clicked on the Display button, and it 
displays the output of that command. . 


Subsequently, every time you click on the Display button in any of the three 
dialog boxes listed, the debugger appends the new command generated to the 
current command list and updates AUTO to display the output from the entire 
command list. 


1.3.2.4 Predefined Instruction Window (INST) 
Window INST displays the decoded VAX assembly-language instruction stream 


of your program. This is the exact code that is executing, including the effects of 
any compiler optimization. 


You can use INST in two basic ways: 
¢ By default, INST automatically displays the instructions for the routine 


in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 


¢ In addition, you can use INST to display the instructions for any part of your 
program. 


By default, INST is not displayed on the screen. To open INST, choose Window 
Setups from the Customize menu. Clicking on a window layout of the Window 
Setups submenu enables you to place INST next to either window SRC or window 
REG. . 


If your program was optimized during compilation, the window layout that places 
windows SRC and INST side by side enables you to readily compare the source 
code and the decoded instruction stream. 


See Section 1.5.6 for more information about displaying instructions. 
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1.3.2.5 Predefined Register Window (REG) 


Window REG displays the current values, in hexadecimal format, of the VAX 
general registers (RO to R11, AP, FP, SP, and PC), the four condition code bits (C, 
V, Z, and N) of the processor status longword (PSL), and as many of the top stack 
values as can be displayed through the window. 


The values contained in the registers are updated each time the debugger gains 
control. 


By default, REG is not displayed on the screen. To open REG, choose Window 
Setups from the Customize menu. Clicking on the third layout of the Window 
Setups submenu enables you to place REG next to window INST. 


1.3.3 Using the Pop-Up Menu 


The debugger’s pop-up menu (see Figure 1-6) enables you to perform several 
common operations without having to pull down a menu in the main window. 


Figure 1-6 Pop-Up Menu over Source Window 





bad VAX DEBUG: SRC module EIGHT QUEENS — 2: _— on oie dt LAE | 
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37: REPEAT Oo 
38: I := I+1; 
39: Safe := A[I] AND B[I+J] AND C[I-J]; 
oy IF EESZ3 THEN 
BEGIN 
{ a: Setqueen; 
X{J] := I; Step Inte Routine 
re IF J < 8 THEN 
Step Over Routine 
4S: Trycol(J+1) ss 
46: ELSE Step To Return 
47; Print; Step By Instruction 
Tee ek ee Step By Line 


Set Break 
View Current Location 





For an explanation of the pop-up menu items, use the pop-up menu’s context- 
sensitive help (see Section 1.5.1). All pop-up menu functions can also be 
performed through other means. 


To use the pop-up menu, proceed as follows: 
1. Position the pointer within a debugger window. 


2. Press and hold MB2 to display the pop-up menu, then drag to the desired 
menu item and release MB2. 


Note that the behavior of the Examine, Evaluate, and Set Break menu items 
depends on whether you selected text before invoking the pop-up menu. 


1.4 Getting Started with the Debugger 
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This section walks you through the following basic steps with a sample program, 
EIGHTQUEENS. The complete source code for the program is shown in 
Section 1.7. 


1. Set a breakpoint to suspend execution at a routine call statement. 
2. Execute the program to the breakpoint. 
3. Execute the program into the called routine. 
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4. While execution is suspended within the routine, display the current value of 
a variable. 


5. Assign another value to the variable. 
6. Display source code in the calling routine. 


Figure 1-7 shows the source window, SRC, at debugger startup. Execution is 
suspended at line 1 (the boxed line) of module EIGHTQUEENS. 


Figure 1-7 Source Window at Debugger Startup 
RL_VAX DEBUG: SRC — module EIGHTQUEENS 


Edit commands 
ii PROGRAM Eightqueens(OQUTPUT); sss CC ™t~—‘“SCOCCCCY 


: INTEGER; 

: ARRAY[1..8] OF BOOLEAN; 
: ARRAY[2..16] OF BOOLEAN; 
: ARRAY[-7..7] OF BOOLEAN; 


B 
Cc 
X : ARRAY[1..8] OF INTEGER; 
Safe : BOOLEAN; K: INTEGER; 


PROCEDURE Print; 
BEGIN (* Print *) 





1.4.1 Setting a Breakpoint 


In this section, a breakpoint is set on line 60 of module EIGHTQUEENS. Line 60, 
which is hidden below the window pods) in Figure 1-7, contains a call to routine 
TRYCOL (see Figure 1-8). 


Proceed as follows: 
1. Scroll the source window to display line 60. 


2. Double click on any part of line 60. When setting a breakpoint, you can select 
any portion of a line in the source window. For example, you could select the 
number 60, as shown in Figure 1-8, or the word TRYCOL. The breakpoint 
would be set on line 60 in either case. 


3. Choose Set Break from the pop-up menu. 
A breakpoint is now set on line 60—specifically, at the beginning of line 60, before 
the call to routine TRYCOL is executed. 


1.4.2 Executing the Program to the Breakpoint 


To execute the program from the current location (line 1) to the breakpoint at line 
60, click on the Go button in the main window. 


When execution reaches the breakpoint, the source window is updated 
automatically: line 60 is boxed, indicating that execution is now suspended 
at the call statement to routine TRYCOL (see Figure 1-9). 
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Figure 1-8 Setting a Breakpoint with the Pop-Up Menu 


Bi] VAX DEBUG: SRC ~ module EIGHTQUEENS TE eae a ea oe (Ballz 


File Edit Commands i HEL) 


: BEGIN (* Eightqueens *) Examine 
FOR I := 1 TO 6 DO Evaluate 
A[T] eect Step Into Routine 
FOR I :# TO 16 DO 
B[I] := TRUE; Step Over Routine 
FOR I := -?7 TO 7 DO Step To Return 
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: END. (* Eightqueens *) 


View Current Location 


VAX DEBUG: SRC ~ module EIGHTQUEENS LHIET | 


File Edit | Commands : 


: BEGIN (* Eightqueens *) 
FOR I := 1 TO 8 DO 
A[I] := TRUE; 
:= 2 TO 16 DO 


:= TRUE; 
:= -7 TO 7 DO 





Whenever the source window is updated as a result of program execution, the 
boxed line indicates the line to be executed next. 


1.4.3 Executing the Program into a Called Routine 


While execution is suspended at line 60, at the call statement to routine TRYCOL, 
choose Step Into Routine from the pop-up menu to execute the program one step 
unit into the routine (see Figure 1-10). 


After this Step command has been entered, the source window is updated, 
showing that execution is now suspended at line 36, within routine TRYCOL (see 
Figure 1—11). 


The Step command is used in this section and the next to execute the program 
one source line at a time. Note that, in this mode of operation, the Step command 
executes one or more executable lines at a time, skipping over any other lines. 
Executable lines are those for which instructions were generated by the compiler. 
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Figure 1-10 Stepping into a Called Routine 
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WRITELN; Set Break 


: END. (* Eightqueens *) 
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C{I-J] := TRUE; 
END; (* Retlovequeen *} 


BEGIN (* Trycol *) 


+ 
:= A[I] AND B[LI+J] AND C[I-J]; 
IF Safe THEN 
BEGIN 
Setqueen; 





1.4.4 Displaying the Current Value of a Variable 


The value of the Boolean variable SAFE is obtained in this section. It is obtained 
after the assignment statement at line 39, in routine TRYCOL, has been executed 
(see Figure 1-11). 


To execute the program from the current location at line 36 past line 39 (for 
example, to line 42), click on the Step button repeatedly until line 42 is boxed (see 
Figure 1-12). 


To display the current value of the variable SAFE, proceed as follows: 
1. Double click on the word SAFE in the source window to select that word. 
2. Choose Examine from the pop-up menu. 


The value of SAFE (True) is now displayed in window OUT. The debugger 
displays the variable name using its full path name (EIGHTQUEENS\ SAFE), 
indicating that SAFE is declared in module EIGHTQUEENS. 


Note that the Current Entity field in the main window is now updated to identify 
the last entity that was examined, namely the variable SAFE. 
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Figure 1-12 Examining a Selected Variable with the Pop-Up Menu 
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1.4.5 Assigning a Value to the Variable 
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Assume that the variable SAFE is still selected in the source window. To change 
the. value of SAFE from True to False, proceed as follows (see Figure 1-13): 


1. Choose Variables from the Data menu in the main window, then choose 
Deposit into Variable... from the submenu. . 
When the Deposit into Variable dialog box is displayed, note that the selected 
word, SAFE, fills the Variable text-entry field. Thus, you do not have to enter 
the variable name from the keyboard. 

2. Enter the word False in the Language Expression field. This is the value to 
be assigned to (deposited into) the variable. 

3. Click on OK or Apply. | 


Variable SAFE now has the value False. You can verify this by choosing Examine 


from the pop-up menu. 
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Figure 1-13 Assigning a Value to a Variable 
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1.4.6 Displaying Source Code for the Calling Routine 


By default, the source window shows the source code for the routine in which 
execution is suspended, and the name of the routine is identified in the Call 
Frame field of the main window. 


In this example, execution is currently suspended within routine TRYCOL of 
module EIGHTQUEENS. The Call Frame field in Figure 1-12 displays the 
routine path name, EIGHTQUEENS\ TRYCOL. 


The number 0 in the Call Frame field indicates that the routine whose source 


code is displayed is the routine at the top of the call stack (where execution is 
suspended). 


If, as in this example, execution is suspended within a called routine, you can 
display the source code for the calling routine by clicking once on the Call Frame 
down arrow button. 


Clicking once displays the source code for routine EIGHTQUEENS (the main 
program), as shown in Figure 1-14. The boxed line identifies the line where 
execution will continue in that routine (line 61, which follows the call statement). 
The Call Frame field now displays the number 1, followed by the name of that 
routine. The number indicates the level, relative to the top of the call stack (level 
0), of the routine whose source code is displayed. 
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Figure 1-14 Displaying Source Code in the Calling Routine 
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In general, clicking on the Call Frame arrow buttons enables you to display the 


source code for any routine up or down the call stack. 


A Call Frame arrow button that is dimmed indicates that the scope reference is 


at the end of the call stack. 


1.5 Using the Debugger 


The remaining sections of this chapter explain how to use the debugger to 
perform basic functions. After an introduction, most sections point to an online 


help topic for additional information. 


1.5.1 Displaying Online Help About the Debugger 
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When you first invoke the debugger’s online help system, it might take 


up to a minute to display the first help topic. Subsequent help topics are 


displayed within a few seconds after you request them. 


Three kinds of online help about the debugger and debugging are available during 


a debugging session: 


¢ Context-sensitive help, which is available for any item in a debugger window, 


menu, or dialog box 


¢ Conceptual and task-oriented help, which consists of an introductory help 


topic named Overview and several subtopics on specific subjects 


¢ Help about the debugger’s command interface, which is available through the 


COMMAND box 


The technique for displaying each kind of online help is described in the following 


sections. 
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1.5.1.1 Displaying Context-Sensitive Help 


Context-sensitive help about the debugger is available for any item in a debugger 
window, menu, or dialog box. 


To display context-sensitive help: 

1. Point to an item. 

2. Press and hold the Help key. 

3. Click on either MB1, MB2, or MB3. 

4. Release the Help key. 

Context-sensitive help for dialog boxes is structured in the following way: 


¢ The same help text is displayed for any location of the pointer within a dialo 
box. 


e¢ The introductory help text describes how to use the dialog box for a typical 
operation. 


¢ In most cases, a separate additional topic is devoted to each item in the dialog 
box (button, menu, and so on). These topics are listed in the order that the 
items they describe appear in the dialog box, from top to bottom. 


¢ Other topics provide task-oriented and conceptual discussions, where 
applicable. 


When using context-sensitive help, you should also display the Overview help 
topic and look for related information in the list of additional topics. 


1.5.1.2 Displaying the Overview Help Topic and Subtopics 


The Overview help topic and subtopics provide conceptual and task-oriented help 
about the debugger and debugging. These topics supplement the information that 
is available through context-sensitive help. 


To display the Overview topic, use any one of the following techniques: 
¢ Choose Overview from the Help menu in the main window. 


¢ Ensure that a debugger window has the input focus, then press and release 
the Help key. 


¢ Choose Go To Overview from the View menu of a debugger help window. 


Then, to obtain information about a particular subject, choose a topic from the 
list of additional topics. 


1.5.1.3 Displaying Help About the Debugger’s Command Interface 
Help about the debugger’s command interface is available through the 


COMMAND box. 
¢ To open the COMMAND box, choose Show Command... from the Customize 
menu. 


e To list the help topics, enter the HELP command at the DBG> prompt. 


e For an explanation of the command-interface help system, enter the command 
HELP HELP. 
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1.5.2 Debugger Diagnostic Messages 


Debugger diagnostic messages include numerous informational messages (severity 
level I) that provide feedback during a debugging session. (For an explanation 

of severity levels, choose Overview from the Help menu, then choose Debugger 
Diagnostic Messages.) 


To reduce the time involved in acknowledging informational messages, only those 
debugger messages that have severity levels of W, E, or F are displayed in a 
message box. 


You can get context-sensitive help on any debugger message that is displayed in a 
message box. 


By default, all debugger messages (including those of severity level I) are 
displayed in window OUT. Thus, debugger messages of severity level greater than 
I are displayed both in a message box and in window OUT. 


Messages displayed in a message box show only the message text. Messages 
displayed in window OUT show the message text, identifier, severity, and facility. 


1.5.3 Interrupting Program Execution and Aborting Debugger Operations 


To interrupt program execution during a debugging session, click on the Stop 
button in the main window. This is useful if, for example, the program is in an 
infinite loop. 


To abort a debugger operation that is in progress, click on the Stop button in the 
main window. This is useful if, for example, the debugger is displaying a long 
stream of data. 


Clicking on the Stop button does not end the debugging session. Clicking on 
the Stop button when the program is not running or when the debugger is not 
performing an operation has no effect. 


1.5.4 Ending a Debugging Session 


1-20 


To end a debugging session, choose either Exit or Quit from the File menu in the 
main window. 


If your program has application-declared exit handlers, Exit executes these 
handlers. Quit gives you the option of executing application-declared exit 
handlers (a dialog box is displayed in such cases). 


Unless you are debugging a multiprocess program, you can also end the 
debugging session by choosing Exit or Quit from any debugger window (not 
just the main window). 


For multiprocess programs, choosing Exit or Quit from a debugger window other 
than the main window has the following effect: 


¢ Ifthe window is not process specific, terminates the visible process 


¢ Ifthe window is process specific, terminates the process associated with that 
window 


The following message, displayed in the output window during a debugging 
session, indicates that your program has completed normally: 


¢DEBUG-I-EXITSTATUS, is ‘SSYSTEM-S-NORMAL, normal successful completion’ 
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If you want to continue debugging after seeing this message, it is usually best to 
end the session and start a new one. You can restart execution from within the 
debugging session (by choosing Go... from the Control menu and then specifying 
a location in the Go dialog box). However, this technique can produce unexpected 
results if, for example, some variables have different values from when you first 
ran the program. 


1.5.5 Displaying Source Code 


By default, window SRC automatically displays the source code for the module in 
which execution is currently suspended. 


In addition, window SRC has the source attribute by default. Therefore, you can 
also use SRC to display the source code for any part of your program (if source 
code is available for display): 


¢ ‘You can display the source code for any routine on the call stack by clicking 
on the Call Frame arrow buttons in the main window. 


The number shown in the Call Frame field indicates the relative level of the 
routine on the call stack. Call frame 0 denotes the routine at the top of the 
call stack, where execution is suspended. Call frame 1 denotes the calling 
routine, and so on. 


¢ You can display arbitrary source lines in any module by choosing View 
Source... from the Commands menu of window SRC. 


° You can display the source line associated with a code location (for example, a 
routine declaration) by choosing Examine Code... from the Code submenu of 
the Data menu. 


After manipulating the contents of window SRC, you can display the location at 
which execution is suspended by choosing View Current Location from the pop-up 
menu. 


If the debugger cannot locate source lines for display, it issues a diagnostic 
message. 


For more information, choose Overview from the Help menu, then choose 
Displaying Source Code. 


1.5.6 Displaying Decoded VAX Instructions 


By default, window INST automatically displays the decoded instruction stream 
for the routine in which execution is currently suspended. 


If window INST has the instruction attribute, it is also updated by any command 
that you enter to display instructions. If no window has the instruction attribute, 
the output of such commands is directed at window OUT. Note that opening 
window INST through the Window Setups submenu of the Customize menu 
automatically assigns the instruction attribute to that window. 


You can display instructions in window INST as follows: 


¢ You can display the instruction stream for any routine that is on the call 
stack by clicking on the Call Frame arrow buttons in the main window. 


¢ You can display the instructions that are associated with a code location 
(for example, a routine declaration) by choosing View Instructions from the 
Commands menu of window INST, or by choosing Examine Code... from the 
Code submenu of the Data menu. 
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When you choose Examine Code..., you have the option of displaying detailed 
information about the instruction operands. 


After manipulating the contents of window INST, you can display the location at 
which execution is suspended by choosing View Current Location from the pop-up 
menu. 


For more information, choose Overview from the Help menu, then choose 
Displaying Decoded VAX Instructions. 


1.5.7 Specifying Address Expressions in Dialog Boxes 


Several dialog boxes (for example, the Break dialog box) require you to enter an 
address expression. An address expression is an entity that denotes a memory 
address or a register. Do not confuse an address expression with a language 
expression, which denotes a value (see Section 1.5.9.4). 


The debugger is a symbolic debugger. Therefore, although you can specify a 
memory address or register directly in a dialog box, you usually specify symbolic 
address expressions. These include routine names, variable names, program 
labels, and source line numbers. The debugger associates a symbolic address 
expression with a unique memory address, range of addresses, or register. The 
debugger also recognizes the compiler-generated type that is associated with a 
symbolic address expression. 


Address expressions are associated with either code (VAX assembly-language 
instructions) or data. The kind of address expression you need to specify in a 
dialog box depends on the action you are about to perform and is indicated in the 
help text for that dialog box. For example, when setting a breakpoint, you specify 
an address expression that is associated with code; when setting a watchpoint, 
you specify an address expression that is associated with data (a variable name, 
in most cases). 


You can fill the Address Expression field of a dialog box in two ways: 


¢ By selecting text in a window. If you select the text before you open the dialog 
box, the text is automatically inserted in the Address Expression field. 


e By entering text directly from the keyboard. 


The help text for a dialog box explains the conventions for filling the Address 
Expression field. . 


For more information, choose Overview from the Help menu, then choose 
Specifying Address Expressions. 


1.5.8 Controlling and Monitoring Program Execution 
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This section explains how to perform the following tasks: 

e Start or resume program execution 

e¢ Execute the program to the next source line, instruction, or other step unit 
e Use breakpoints to suspend execution at points of interest 


e Use tracepoints to trace the execution path of your program through specified 
locations 


¢ Use watchpoints to monitor changes in the values of variables 
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To determine where execution is suspended at any time during a debugging 
session, use the techniques described in Section 1.5.5 and Section 1.5.6. You can 
also choose Call Stack... from the Data menu to display the sequence of routine 
calls that are currently active on the call stack and to obtain detailed information 
about the call stack. 


1.5.8.1 Starting or Resuming Program Execution 
Use the Go command to start or resume program execution. 


To start execution from the current location, click on the Go button in the main 
window. 


To start execution from another location, choose Go... from the Control menu and 
specify the location in the Go dialog box. 


After it is started with the Go command, program execution continues until one 
of the following events occurs: 


e The program completes execution 

¢ A breakpoint is reached 

e A watchpoint is activated 

e An exception is signaled 

¢ You click on the Stop button in the main window 


For more information, choose Overview from the Help menu, then choose Starting 
and Resuming Execution (Go Command). 


1.5.8.2 Executing the Program by Step Unit 
Use the Step command to execute the program one or more step units at a time. 


By default, a step unit is one line of source code; and, by default, the debugger 
notifies you of the completion of a Step command by displaying a "stepped 
to... " message and the source line where execution is suspended. 


To execute one step unit, click on the Step button in the main window. 


You can use the pop-up menu for some common step options (for example, step 
into routine, step by instruction). 


To execute these and other step options, or to change the step unit or any Step 
command default, choose Step... from the Control menu. For example, you can 
make the default step unit signify "execute one instruction". 


For more information, choose Overview from the Help menu, then choose 
Executing the Program by Step Unit (Step Command). 


1.5.8.3 Suspending and Tracing Execution with Breakpoints and Tracepoints 
A breakpoint is a location in your program at which execution is to be suspended. 
Typical locations are routine declarations, program labels, and specific lines of 
source code. At a breakpoint, you can step into a routine, check the current value 
of a variable, and so on. 


In addition to specifying unique locations, you can set breakpoints on every source 
line or on certain classes of VAX assembly-language instructions. You can also 
set breakpoints on certain kinds of events, such as exceptions and tasking events. 
And you can set conditional breakpoints that trigger only when a specified 
expression is evaluated to be true. 
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A tracepoint is like a breakpoint, except that execution continues after the 
debugger reports that the tracepoint has been reached. Tracepoints enable you 
to monitor the path of execution of your program through specified locations (for 
example, through routine calls). As with breakpoints, you can trace through 
classes of instructions, monitor events, and set conditional tracepoints. 


In general, to set, identify, or cancel breakpoints or tracepoints, choose Break... 
from the Control menu. . 


For more information, choose Overview from the Help menu, then choose Using 
Breakpoints and Tracepoints. 


1.5.8.4 Monitoring Changes in Variables with Watchpoints 


A watchpoint is a memory address, register, or (typically) a variable declared in 
the program whose value is monitored during program execution. If the value 
changes, the debugger suspends execution and reports the old and new values. 


Note that you can set a watchpoint on a nonstatic (stack or register) variable only 
when program execution is currently suspended within the scope of its defining 
routine—that is, when the defining routine is active on the call stack. 


To set, identify, or cancel watchpoints, choose Watch... from the Control menu. 
As with breakpoints and tracepoints, you have several options for setting 
watchpoints. 


For more information, choose Overview from the Help menu, then choose Using 
Watchpoints. 


1.5.9 Examining and Manipulating Program Data 


The debugger enables you to manipulate variables declared in your program, code 
locations (locations containing VAX instructions), memory addresses, registers, 
and language expressions. 


1.5.9.1 Operations with Variables 


To manipulate variables in your program, choose Variables from the Data menu. 
The Variables submenu provides the following operations: 


¢ To display the value of a variable, choose Examine Variable... 
¢ To assign a value to a variable, choose Deposit into Variable... 


¢ To display information about a variable, such as its type, memory address or 
register, and path name, choose Show Variable... 


Note that you can examine a nonstatic (stack or register) variable only when 
program execution is currently suspended within the scope of its defining 
routine—that is, when the defining routine is active on the call stack. 


For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data, then choose Operations with 
Variables. 


1.5.9.2 Operations with Code Locations 
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To manipulate code locations in your program (locations with VAX assembly- 
language instructions) choose Code from the Data menu. The Code submenu 
provides the following operations: 


¢ To display the following information, choose Examine Code... 


— The source line for a code location (for example, for a routine declaration). 
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— The VAX instructions at a code location (for example, the instruction 
at the current PC value, where execution is suspended). The program 
counter (PC) is a VAX register that contains the address of the instruction 
to be executed next. 


¢ To deposit a VAX instruction at a memory address or into a register, choose 
Deposit Code... 


¢ To display the memory address of a routine, line number, or other code 
location, choose Show Address... 


For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data, then choose Operations with Code 
Locations. 


See also Section 1.3.2.4 and Section 1.5.6 for information about displaying 
instructions associated with your program. 


1.5.9.3 Operations with Addresses or Registers 
To manipulate memory addresses or registers, choose Addresses or Registers 
from the Data menu. The Addresses or Registers submenu provides the following 
operations: 


¢ To display the value stored at an address or in a register, choose Examine 
Address or Register... 


¢ To change the value stored at an address or in a register, choose Deposit into 
Address or Register... 


¢ To display the symbol (if any) that is associated with an address or register, 
choose Symbolize Address or Register... 


For more information, choose Overview from the Help menu, then choose 
Examining and Manipulating Program Data, then choose Operations with 
Addresses or Registers. 


1.5.9.4 Evaluating Language Expressions 


To evaluate a language expression, choose Language Expressions... from the Data 
menu. 


The debugger recognizes the operators and expression syntax of the currently set 
language. For example, if your program has an integer variable named WIDTH, 
you can use the Language Expressions dialog box to evaluate the expression 
WIDTH + 7. The debugger adds 7 to the current value of WIDTH and displays 
the result. 


For more information, choose Overview from the Help menu, then choose 
Specifying and Evaluating Language Expressions. See also Section 1.5.13 for 
information about debugging multilanguage programs. 


1.5.10 Controlling Access to Symbols in Your Program 


To have full access to the symbols that are associated with your program (variable 
names, routine names, source code, line numbers, and so on), you must compile 
and link the program using the /DEBUG qualifier, as explained in Section 1.2.1. 


Under these conditions, the way in which the debugger handles these symbols 
is transparent to you, in most cases. However, the following two areas might 
require action: 


¢ Setting and canceling modules 
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¢ Resolving symbol ambiguities 


These two subjects are discussed in the next sections. For more information, 
choose Overview from the Help menu, then choose Controlling Access to Symbols 
in Your Program. 


1.5.10.1 Setting and Canceling Modules 


To facilitate symbol searches, the debugger loads symbol information from the 
executable image into a run-time symbol table (RST), where that information can 
be accessed efficiently. Unless symbol information is in the RST, the debugger 
does not recognize or properly interpret the associated symbols. . 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 


At debugger startup, only the module containing the image transfer address 
is set. Subsequently, whenever execution of the program is interrupted, the 
debugger sets the module that contains the routine in which execution is 
suspended. This enables you to reference the symbols that should be visible 
at that location. 


If you try to reference a symbol in a module that has not been set, the debugger 
warns you that the symbol is not in the RST. For example: 


SDEBUG-W-NOSYMBOL, symbol 'X’ is not in symbol table 


You must then set the module containing that symbol explicitly. To set a module, 
choose Modules... from the Data menu. The Modules dialog box lists the modules 
of your program and identifies which modules are set. 


For more information, choose Overview from the Help menu, then choose 
Controlling Access to Symbols in Your Program, then choose Setting and 
Canceling Modules. 


1.5.10.2 Resolving Symbol Ambiguities 
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Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 


In most cases, the debugger resolves symbol ambiguities automatically. First 

it uses the scope and visibility rules of the currently set language. In addition, 
because the debugger permits you to specify symbols in arbitrary modules (to set 
breakpoints and so on), the debugger uses the ordering of routine calls on the call 
stack to resolve symbol ambiguities. 


In some cases, however, the debugger might respond as follows when you specify 
a symbol that is defined multiple times: 


¢ It might issue a "symbol not unique" message because it is not able to 
determine the particular declaration of the symbol that you intended. 


e It might reference a symbol declaration other than the one you want. 


To resolve such problems, you must specify a scope where the debugger should 
search for the particular declaration of the symbol. There are two techniques: 


e Specify a path name prefix with the symbol. For example, if the variable 
X is defined in two modules named COUNTER and SWAP, the path name 
SWAP\X uniquely specifies the declaration of X in module SWAP. This 
technique can always be used to resolve symbol ambiguities. 
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e Ifthe different declarations of the symbol are within routines that are 
currently active on the call stack, use the Call Frame arrow buttons in the 
main window to reset the reference for looking up symbols to the appropriate 
call frame. With this technique you do not need to specify a path name prefix. 


For more information, choose Overview from the Help menu, then choose 
Controlling Access to Symbols in Your Program, then choose Resolving Symbol 
Ambiguities. 


1.5.11 Using the Debugger’s Command Interface 


The debugger is available in a command interface that runs on terminals and 
workstations (see Part II of this manual). When using that interface, you interact 
with the debugger by entering commands at the debugger prompt (DBG>). 


When using the debugger’s DECwindows interface, you can open the COMMAND 
box, which enables you to enter debugger commands at the DBG> prompt: 


¢ To open the COMMAND box for just one command, press the DO key. 


¢ To open the COMMAND box indefinitely, choose Show Command... from 
the Customize menu. Choosing Hide Command from that menu closes the 
COMMAND box. 


You can also enter debugger commands in debugger command procedures 
and initialization files for execution under the DECwindows environment (see 
Section 1.5.12). 


The following commands are disabled in the debugger’s DECwindows interface: 


CANCEL WINDOW 

EXPAND 

MOVE 

SELECT/PROGRAM 

SET MARGINS 

SET MODE NOSCREEN 

SET OUTPUT [NO]SCREEN_LOG 
SET OUTPUT [NO]JTERMINAL 
SET TERMINAL 

SET WINDOW 

SHOW MARGINS 

SHOW TERMINAL 

SHOW WINDOW 


The debugger issues an error message when you try to enter any of these 
commands interactively from the COMMAND box or when the debugger executes 
a command procedure containing any of these commands. 


For more information, choose Overview from the Help menu, then choose Using 
the Debugger’s Command Interface. 


1.5.12 Using Log Files, Initialization Files, and Command Procedures 


When you use the debugger’s DECwindows interface, each of your actions 
results in one or more debugger commands. These commands are echoed in the 
COMMAND box by default. 


You can record in a log file the debugger commands that you enter directly or 
indirectly during a debugging session and the debugger’s responses to those 
commands. You can use log files to keep a record of your debugging sessions, 
or you can use them as command procedures in subsequent sessions. For more 
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information, choose Overview from the Help menu, then choose Logging a 
Debugging Session into a File. 


You can create an initialization file containing debugger commands to set your 
default debugging modes, debugger window characteristics, and so on. When you 
invoke the debugger, those commands are executed automatically to tailor your 
debugging environment. For more information, choose Overview from the Help 
menu, then choose Using a Debugger Initialization File. 


You can direct the debugger to execute a command procedure (a file containing 
a sequence of debugger commands) to re-create a debugging session, to continue 
a previous session, or to avoid typing the same debugger commands many times 
during a debugging session. You can pass parameters to command procedures. 
For more information, choose Overview from the Help menu, then choose Using 
Debugger Command Procedures. 


1.5.13 Debugging Multilanguage Programs 


Within the same debugging session, you can debug modules whose source code is 
written in different languages. 


By default, the debugger language remains set to the language of the main 
program throughout the debugging session, even if execution is suspended 
within a module written in another language. To take full advantage of symbolic 
debugging with such modules, you can set the debugging context to another 
language by choosing Language from the Customize menu. 


For more information, choose Overview from the Help menu, then choose | 
Debugging Multilanguage Programs and Debugger Support for Languages. 


When debugging in any language, be sure also to consult the documentation 
supplied with that language. 


1.5.14 Debugging Shareable Images 


By default, the main (executable) image of your program is your debugging 
context. 


By setting your debugging context to a shareable image that is linked with your 
program, you have access to the symbols declared in that image. To set your 
debugging context to another image, choose Images... from the Data menu. 


For more information, choose Overview from the Help menu, then choose 
Debugging Shareable Images. 


1.5.15 Debugging Tasking (Multithread) Programs 
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Tasking programs have multiple threads of execution within a VMS process. 
Examples of such programs are programs that use DECthreads or POSIX 1003.4a 
services, and programs that use language-specific tasking services (for example, 
Ada tasking programs). 


When using the debugger with a tasking program, you can control the execution 
of individual tasks and display information about one or more tasks or the entire 
tasking system. 


To manipulate tasks, choose Tasks... from the Data menu. See also Chapter 12 of 
this manual. 
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1.5.16 Debugging Multiprocess Programs 


To debug a multiprocess program (a program that runs in more than one process), 
you must establish a multiprocess debugging configuration before invoking the 
debugger. That configuration enables you to interact with several processes from 
one debugging session. 


Enter the following command to establish a multiprocess debugging configuration: 
$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 


After you have invoked the debugger, you can control the execution of individual 
processes, examine data associated with specific processes, display information in 
process-specific windows, and so on. 


To manipulate processes, choose Processes... from the Data menu. For more 
information, choose Overview from the Help menu, then choose Debugging 
Multiprocess Programs. . 

1.5.17 Debugging Vectorized Programs 


When using the debugger with a vectorized program (a program that uses VAX 
vector instructions), you can perform tasks such as the following: 


¢ Control and monitor the execution of vector instructions with breakpoints, 
watchpoints, and so on 


e Examine and deposit into the vector control registers (VCR, VLR, and VMR) 
and the vector registers (VO to V15) 


e Examine and deposit vector instructions and their operands 


¢ Perform masked operations on vector registers to display only certain register 
elements or override the masking associated with a vector instruction 


© Control synchronization between the scalar and vector processors 
For more information, choose Overview from the Help menu, then choose 
Debugging Vectorized Programs. 


1.5.18 Using the Keypad to Enter Commands 


When you invoke the debugger, a few commonly used debugger command 
sequences are automatically assigned to the keys on the numeric keypad (to the 
right of the main keyboard). Thus, you can perform certain functions either by 
choosing an item from a menu or by pressing a keypad key. 


The predefined key functions are identified in Figure 1-15. 
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Figure 1-15 Keypad Key Functions Predefined by the Debugger—DECwindows 
Interface 
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Most keypad keys have three predefined functions—DEFAULT, GOLD, and 
BLUE. 


¢ To enter a key’s DEFAULT function, press the key. 


¢ To enter its GOLD function, first press and release the PF1 (GOLD) key, and 
then press the key. 


¢ To obtain its BLUE function, first press and release the PF4 (BLUE) key, and 
then press the key. 


In Figure 1-15, the DEFAULT, GOLD, and BLUE functions are listed within each 
key’s outline, from top to bottom, respectively. For example: 


¢ Pressing keypad key 0 enters the STEP command (like clicking on the Step 
button in the main window). 


¢ Pressing key PF1 and then keypad key 0 enters the STEP/INTO command 
(like choosing Step Into Routine from the pop-up menu). 


¢ Pressing key PF4 and then keypad key 0 enters the STEP/OVER command 
(like choosing Step Over routine from the pop-up menu). 


You can redefine keypad key functions. 
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For more information, choose Overview from the Help menu, then choose 
Entering Debugger Commands from the Keypad. 
1.6 Additional Options for Invoking the Debugger 


Section 1.2 describes how to compile and link your program prior to debugging, 
establish the default debugging configuration for one-process programs, and 
invoke the debugger in the usual way from a DECterm window. 


The sections that follow describe other options for invoking the debugger: 
¢ Invoke the debugger from a FileView window 
e Interrupt a program that is executing freely and then invoke the debugger 


e Override the debugger’s default (DECwindows) interface to achieve the 
following: 


— Display the debugger’s DECwindows interface on another workstation 


— Display the debugger’s command interface in a DECterm window, along 
with any program input/output 


— Display the debugger’s command interface and program input/output in 
separate DECterm windows 


In all cases, before invoking the debugger, first compile and link the modules of 
your program and establish the appropriate debugging configuration as explained 
in Section 1.2.1, Section 1.2.2, and Section 1.5.16. 

Note 


You cannot run a program under debugger control over a DECnet link. 
Both the image to be debugged and the debugger must reside on the same 
node. 


For more information, including details on compilation and linking options that 
affect debugging, choose Overview from the Help menu, then choose Options for 
Invoking the Debugger. 


1.6.1 Invoking the Debugger from a FileView Window 


To invoke the debugger from a FileView window, proceed as follows: 

1. Choose Run from the FileView Files menu. A dialog box is displayed. 
2. Specify the executable image file to be debugged. 

3. Choose the Debug option. 

4. Click on OK. 


1.6.2 Invoking the Debugger with the DCL DEBUG Command 


You can invoke the debugger while your program is executing freely (for example, 
if you suspect that the program might be in an infinite loop or if you see erroneous 
output). 


To invoke the debugger in this manner, proceed as follows: 


1. Enter the DCL command RUN/NODEBUG to execute the program without 
debugger control. 
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2. Press Ctrl/Y to interrupt the executing program. Control then passes to the 
DCL command interpreter. 


3. Enter the DCL command DEBUG to activate the debugger. When the 
debugger comes up, it displays the main, source, and output windows, sets 
the language-dependent parameters to the language of the module where 
execution was interrupted, and executes any user-defined initialization file. 


For example: 


$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
$ LINK/DEBUG EIGHTQUEENS 
$ RUN/NODEBUG EIGHTQUEENS 


Interrupt 
$ DEBUG 


[invokes debugger] 


To help you identify where execution was interrupted, look at the source window 
and choose Call Stack... from the Data menu to identify the sequence of routine 
calls on the call stack. 


1.6.3 Overriding the Debugger’s Default Interface 


By default, if your workstation is running VMS DECwindows, the debugger comes 
up in the DECwindows interface on the workstation specified by the DECwindows 
application-wide logical name DECW$DISPLAY. 


This section explains how to override the debugger’s default DECwindows 
interface to achieve the following: 


° Display the debugger’s DECwindows interface on another workstation 


¢ Display the debugger’s command interface in a DECterm window, along with 
any program input/output 


¢ Display the debugger’s command interface and program input/output in 
separate DECterm windows 


The logical name DBG$DECW$DISPLAY enables you to override the default 
interface of the debugger. Note that, in most cases, there is no need to define 
DBG$DECWS$DISPLAY, because the default implies the desired action. 


Section 1.6.3.4 provides more information about the logical names 
DBG$DECW$DISPLAY and DECW$DISPLAY. 


1.6.3.1 Displaying the Debugger’s DECwindows Interface on Another Workstation 
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If you are debugging a DECwindows application that uses most of the screen, 
you might find it useful to run the program on one workstation and display the 
debugger’s DECwindows interface on another. To do so, proceed as follows: 


1. Enter a logical definition with the following syntax in the DECterm window 
from which you plan to run the program: 


DEFINE/JOB DBG$DECW$DISPLAY workstation_pathname 


where workstation_pathname is the path name for the workstation where the 
debugger’s DECwindows interface is to come up. See the description of the 
SET DISPLAY command in the VMS DCL Dictionary for the syntax of this 
path name. 
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It is recommended that you use a job definition. If you use a process 
definition, it must not have the CONFINE attribute. 


2. Run the program from that DECterm window. The debugger’s DECwindows 
interface comes up on the workstation specified by DBG$DECW$DISPLAY. 
The application’s windowing interface comes up on the workstation display 
where it normally does. 


1.6.3.2 Displaying the Debugger’s Command Interface in a DECterm Window 
To display the debugger’s command interface in a DECterm window, along with 
any program input/output, proceed as follows: 


1. Enter the following definition in the DECterm window from which you plan 
to run the program: 


$ DEFINE/JOB DBGSDECWSDISPLAY " " 


You can specify one or more space characters between the quotation marks. It 
is recommended that you use a job definition for the logical name. If you use 
a process definition, it must not have the CONFINE attribute. 


2. Run the program from that DECterm window. The debugger’s command 
interface comes up in the same window. 


For example: 


$ DEFINE/JOB DBGSDECWSDISPLAY " " 

$ PASCAL/DEBUG/NOOPTIMIZE EIGHTQUEENS 
$ LINK/DEBUG EIGHTQUEENS 

$ RUN EIGHTQUEENS 


VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is PASCAL, module set to EIGHTQUEENS 
DBG> 


You can now enter debugger commands as described in Part II of this manual, 
which starts with Chapter 2. 


1.6.3.3 Displaying the Command Interface and Program Input/Output in Separate DECterm 
Windows 
This section describes how to display the debugger’s command interface in a 
separate DECterm window from the DECterm window from which you invoke the 
debugger. This separate window is useful when using the command interface to 
debug a screen-oriented program: 


¢ The program’s input/output is displayed in the window from which you invoke 
the debugger. 


¢ The debugger’s input/output, including any screen-mode display, is displayed 
in the separate window. 


The effect is the same as entering the SET MODE SEPARATE command at the 
DBG> prompt on a workstation running VWS rather than DECwindows. (The 
SET MODE SEPARATE command is not valid when used in a DECterm window.) 


The following example shows how to display the debugger’s command interface in 
a separate debugger window titled “Debugger”. 


1. Create the command procedure SEPARATE _WINDOW.COM shown in 
Example 1-1. 
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2. Execute the command procedure: 


$ @SEPARATE WINDOW 
SDCL-I-ALLOC, _MYNODESTWA8: allocated 


A new DECterm window is created with the attributes specified in 
SEPARATE_WINDOW.COM. 


3. Follow the steps in Section 1.6.3.2 to display the debugger’s command 
interface. The interface is displayed in the new window. 


4. You can now enter debugger commands in the debugger window. Program 
input/output is displayed in the DECterm window from which you invoked 
the debugger. 


5. When you end the debugging session with the EXIT command, control returns 
to the DCL prompt in the program input/output window, but the debugger 
window remains open. 


6. To display the debugger’s command interface in the same window as the 
program’s input/output (as in Section 1.6.3.2), enter the following commands: 


$ DEASSIGN/JOB DBGSINPUT 
$ DEASSIGN/JOB DBGSOUTPUT 


The debugger window remains open until you close it explicitly. 


Example 1-1 Command Procedure SEPARATE_WINDOW.COM 


$ ! Simulates effect of SET MODE SEPARATE from a DECterm window 
o 
$ CREATE/TERMINAL/NOPROCESS - 

/WINDOW_ATTRIBUTES= (TITLE="Debugger", - 

ICON_NAME="Debugger", ROWS=40) - 

/DEFINE_LOGICAL= (TABLE=LNM$JOB, DBGSINPUT, DBGSOUTPUT) 
ALLOCATE DBGSOUTPUT 
EXIT 

! 
! The command CREATE/TERMINAL/NOPROCESS creates a DECterm 
window without a process. 


! The /WINDOW ATTRIBUTES qualifier specifies the window’s 
title (Debugger), icon name (Debugger), and the number 
of rows in the window (40). 


! The /DEFINE LOGICAL qualifier assigns the logical names 
DBGSINPUT and DBGSOUTPUT to the window, so that it becomes 
the debugger input and output device. 


The command ALLOCATE DBGSOUTPUT causes the separate window 
to remain open when you end the debugging session. 


DMN MNMNAMMNONNNONNHONON WM WH 


a ee en ea en ee ee ee oe ee a 


1.6.3.4 Explanation of DBGS$DECW$DISPLAY and DECW$DISPLAY 


1-34 


By default, if your workstation is ranning VMS DECwindows, the debugger comes 
up in the DECwindows interface on the workstation specified by the DECwindows 
application-wide logical name DECW$DISPLAY. DECW$DISPLAY is defined in 
the job table by FileView or DECterm. It points to the display device for the 
workstation. 


For information about DECW$DISPLAY, see the description of the DCL 
commands SET DISPLAY and SHOW DISPLAY in the VMS DCL Dictionary. 
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The logical name DBG$DECW$DISPLAY is the debugger-specific equivalent of 
DECW$DISPLAY. DBG$DECW$DISPLAY is analogous to the debugger-specific 
logical names DBG$INPUT and DBG$OUTPUT. These enable you to reassign 
SYS$INPUT and SYS$OUTPUT, respectively, to specify the device on which 
debugger input and output are to appear. 


The default user interface of the debugger results when DBG$DECW$DISPLAY 
is undefined or has the same translation as DECW$DISPLAY. By default, 
DBG$DECW$DISPLAY is undefined. 


The algorithm that the debugger follows when using the logical definitions of 
DECWS$DISPLAY and DBG$DECW$DISPLAY is as follows: 


1. Ifthe logical name DBG$DECW$DISPLAY is defined, then use it. Otherwise, 
use the logical name DECW$DISPLAY. 


2. Translate the logical name. If its value is not null (if the string contains 
characters other than space characters), the DECwindows interface comes up 
on the specified workstation. If the value is null (if the string consists only of 
space characters), the command interface comes up in the DECterm window. 


1.7 Sample Program EIGHTQUEENS 


Example 1-2 is the Pascal program, EIGHTQUEENS, that is used in Section 1.4. 
Line numbers correspond to the compiler assigned line numbers as displayed in a 
debugger source window. 


The program prints out the possible locations on a chess board at which each of 
eight queens can be positioned safely, without threatening each other. A queen 
can be threatened by another queen on the same row, in the same column, or 
along a diagonal. 


When executed, the program produces several lines of integers. For example: 


IH Oo & CO 
MPoOmMW or 
W Wh CO ~] Ww 
cor inh & ~) 
HA~ IH ON NH 
HOW WH O1 bP 


NOE On en eee 
Oe IHW 
. 


> & Ww OW 
Fr oc ~] 
NNHr DD 
WAND 
IWNr 
ODN oOo 


. ee 
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cw ~) © 


C2 oe 7 a6 
ae ea «ae eo i 
B42 36 2°75 


Each line of output represents a possible safe configuration of the eight queens 
on a standard 8-row by 8-column chess board. For example, the output line 
41582736 indicates that queens can be positioned safely at rows 4, 1, 5, 8, 2, 7, 3, 
and 6 of columns 1 to 8, respectively. 
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Example 1-2 Sample Program EIGHTQUEENS 
1: PROGRAM Eightqueens (OUTPUT) ; 


ve VAR 
33 I : INTEGER; 
4; A : ARRAY{1..8] OF BOOLEAN; 
Si B : ARRAY[2..16] OF BOOLEAN; 
6: C : ARRAY[-7..7] OF BOOLEAN; 
ee X : ARRAY[1..8] OF INTEGER; 
3: Safe : BOOLEAN; K: INTEGER; 
9: 

10: PROCEDURE Print; 

11: BEGIN (* Print *) 

125 FOR K := 1 T0 8 DO 

13% WRITE (X[{K]: 2); 

14: WRITELN; 

Lot END; (* Print *) 

16: 

17s PROCEDURE Trycol(J : INTEGER); 

18: VAR 

ig: I : INTEGER; 

20: 

21: PROCEDURE Setqueen; 

22: BEGIN (* Setqueen *) 

238 A[I] := FALSE; 

24; B[I+J] := FALSE; 

25% C[I-J] := FALSE; 

26: END; (* Setqueen *) 

ols 

28: PROCEDURE Removequeen; 

oA BEGIN (* Removequeen *) 

30: A[I] := TRUE; 

31: B[I+J] := TRUE; 

32: C[I-J] := TRUE; 

33% END; (* Removequeen *) 

34: 

oo BEGIN (* Trycol *) 

abs i := 0; 

STs REPEAT 

38: I := I+1; 

39: Safe := A[I] AND B[I+J] AND C[I-J]; 

40: IF Safe THEN 

41; BEGIN 

42: Setqueen; 

43: X[J].-2= 1) 

44; IF J < 8 THEN 

45: Trycol (J+1) 

46: ELSE 

AT: Print; 

48: Removequeen; 

49; END; 

50: UNTIL I = 8; 

Dis END; (* Trycol *) 


(continued on next page) 
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53: BEGIN (* Eightqueens *) 
54: FOR I := 1 TO 8 DO 


55% A[I] := TRUE; 
56: FOR I := 2 TO 16 DO 
57: B[I] := TRUE; 
58: FOR I := -7 TO 7 DO 
59; C[I] := TRUE; 


60: Trycol(1); 
61:  WRITELN; 
62: END. (* Eightqueens *) 
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Part Il 


Using the Debugger: Command Interface 


This part contains complete information about the VMS debugger’s command 
interface. 


For information about the debugger’s DECwindows interface, see Part I. 


2 


Introduction to the Debugger: Command 
Interface 


This chapter introduces the VMS Debugger’s command interface. For information 
about the debugger’s DECwindows interface, see Chapter 1. 


The following information is provided in this chapter: 
e An overview of the debugger’s features (Section 2.1) 
e Enough information to get you started (Section 2.2) 
e Asample debugging session (Section 2.3) 
e Alist of the debugger commands, by function (Section 2.4) 
After you have read this chapter, consult the rest of this manual for additional 
details about the command interface. 
2.1 Overview of the Debugger 


The debugger is a tool that helps you locate run-time programming or logic 
errors, also known as bugs. You use the debugger with a program that has 
been compiled and linked successfully but does not run correctly. For example, 
the program might give incorrect output, go into an infinite loop, or terminate 
prematurely. 


You locate errors with the debugger by observing and manipulating your program 
interactively as it executes. By entering debugger commands at the terminal, you 
can do the following tasks: 


¢ Control the program’s execution—start the program, stop at points of interest, 
resume execution, and so on 


e¢ Trace the execution path of the program 

e Monitor changes in variables and other program entities 

¢ Monitor exception conditions and language-specific events 

¢ Examine and modify the values of variables, or force events to occur 


¢ In some cases, test the effect of modifications without having to edit the 
source code, recompile, and relink 


These are the basic debugging techniques. After you are satisfied that you have 
found the error in the program, you can edit the source code and compile, link, 
and execute the corrected version. 


As you use the debugger and its documentation, you will discover variations on 
the basic techniques. You can also tailor the debugger for your own needs. The 
next section summarizes the debugger features. 
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2.1.1 Functional Features 


Programming Language Support 

You can use the debugger with the following VAX languages: Ada, BASIC, BLISS, 
C, COBOL, DIBOL, FORTRAN, MACRO-32, Pascal, PL/I, RPG II, and SCAN. 
The debugger recognizes the syntax, data typing, operators, expressions, scoping 
rules, and other constructs of a given language. If your program is written 

in more than one language, you can change the debugging context from one 
language to another during a debugging session with the SET LANGUAGE 
command. 


Symbolic Debugging 

The VMS Debugger is a symbolic debugger. You can refer to program locations by 
the symbols you used for them in your program—the names of variables, routines, 
labels, and so on. You do not need to specify memory addresses or VAX registers 
when referring to program locations, although you can, if you want. 


Support for All Data Types 

The debugger understands all compiler generated data types, such as integer, 
floating point, enumeration, record, array, and so on. It displays the values of 
program variables according to their declared type. 


Flexible Data Format 

The debugger permits a variety of data forms and types for entry and display. By 
default, the source language of the program determines the format used for the 
entry and display of data. You can also impose other formats. For example, by 
using a type or radix qualifier with the EXAMINE command, you can display the 
contents of a program location in ASCII, word-integer, or floating-point format. 


Starting or Resuming Program Execution 


You start or resume program execution with the GO or STEP commands. The 
GO command causes the program to execute until a breakpoint is reached, a 
watchpoint is modified, an exception is signaled, or the program terminates. The 
STEP command enables you to execute a specified number of lines or instructions, 
or up to the next instruction of a specified class. 


Breakpoints 

By setting breakpoints with the SET BREAK command, you can suspend program 
execution at specified locations and check the current status of your program. 
Rather than specify a location, you can also suspend execution on certain classes 
of instructions or on every source line. Also you can suspend execution on certain 


kinds of events, such as exceptions and tasking (multithread) events. 


Tracepoints 

By setting tracepoints with the SET TRACE command, you can monitor the 
path of program execution through specified locations. When a tracepoint 
is triggered, the debugger reports that the tracepoint was reached and then 
continues execution. As with the SET BREAK command, you can also trace 
through classes of instructions and monitor events. 


Watchpoints 


By setting a watchpoint with the SET WATCH command, you can cause execution 
to stop whenever a particular variable or other memory location has been 
modified. When a watchpoint is triggered, the debugger suspends execution 

at that point and reports the old and new values of the variable. 
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Manipulation of Variables and Program Locations 


With the EXAMINE command, you can determine the value of a variable or 
program location. The DEPOSIT command enables you to change that value. You 
can then continue execution to see the effect of the change, without having to 
recompile, relink, and rerun the program. 


Evaluation of Expressions 

With the EVALUATE command, you can compute the value of a source-language 
expression or an address expression. You specify expressions and operators in the 
syntax of the language to which the debugger is currently set. 


Control Structures 


You can use logical control structures (FOR, IF, REPEAT, WHILE) in commands 
to control the execution of other commands. 


Shareable Image Debugging 


You can debug shareable images (images that are not directly executable). 
The SET IMAGE command enables you to reference the symbols declared in 
a shareable image. 


Multiprocess Debugging 


You can debug multiprocess programs (programs that run in more than one VMS 
process). The SHOW PROCESS and SET PROCESS commands enable you to 
display process information and control the execution of images in individual 
processes. 


Task Debugging 


You can debug tasking programs (also known as multithread programs). These 
programs use DECthreads or POSIX 1003.4a services, or use language-specific 
tasking services (for example, Ada tasking programs). The SHOW TASK and SET 
TASK commands enable you to display task information and control the execution 
of individual tasks. 


Vector Debugging 

You can debug vectorized programs (programs that use VAX vector instructions). 
You can control and monitor execution at the vector instruction level, examine 
and deposit vector instructions, manipulate the contents of vector registers, use a 
mask to display specific vector elements, and control synchronization between the 
scalar and vector processors. 

Terminal and Workstation Support 

The debugger supports all VT-series terminals and MicroVAX workstations. 


2.1.2 Convenience Features 
Online Help 
Online help is always available during a debugging session. Online help contains 
information about all debugger commands and selected topics. 
Source Code Display 


You can display lines of source code for all supported languages during a 
debugging session. 
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Screen Mode 

In screen mode, you can display and capture various kinds of information 

in scrollable windows that can be moved around the screen and resized. 
Automatically updated source, instruction, and register displays are available. 
You can selectively direct debugger input, output, and diagnostic messages to 
displays. You can also create "DO" displays that capture the output of specific 
command sequences. 


Keypad Mode 

When you invoke the debugger, several commonly used debugger command 
sequences are assigned by default to the keys of the numeric keypad (if you have 
a VT52, VT100, or LK201 keyboard). Thus, you can enter these commands with 
fewer keystrokes than if you were to type them at the keyboard. You can also 
create your own key definitions. 


Source Editing 

As you find errors during a debugging session, you can use the EDIT command 
to invoke any editor available on your system. You specify the editor you wish 
with the SET EDITOR command. If you use the VAX Language-Sensitive Editor, 
the editing cursor is automatically positioned within the source file whose code 
appears in the screen-mode source display. 


Command Procedures 

You can direct the debugger to execute a command procedure (a file of debugger 
commands) to re-create a debugging session, to continue a previous session, or 
to avoid typing the same debugger commands many times during a debugging 
session. You can pass parameters to command procedures. 


Initialization Files 

You can create an initialization file containing commands to set your default 
debugging modes, screen display definitions, keypad key definitions, symbol 
definitions, and so on. When you invoke the debugger, those commands are 
executed automatically to tailor your debugging environment. 


Log Files 
You can record in a log file the commands you enter during a debugging session 
and the debugger’s responses to those commands. You can use log files to keep 


track of your debugging efforts, or you can use them as command procedures in 
subsequent debugging sessions. 


Symbol Definitions 
You can define your own symbols to represent lengthy commands, address 


expressions, or values in abbreviated form. 


2.2 Getting Started with the Debugger 
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The way you use the debugger depends on several factors: the kind of program 
you are working on, the kinds of errors you are looking for, and your own personal 
style and experience with the debugger. This section explains the following basic 
functions that apply to most situations, 


¢ Compiling and linking your program to prepare for debugging 
e Establishing the debugging configuration 
e Invoking the debugger 


e Ending a debugging session 
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¢ Interrupting program execution and aborting debugger commands 
¢ Entering debugger commands and getting online help 
e¢ Viewing your source code with the TYPE command and in screen mode 


¢ Controlling program execution with the GO, STEP, and SET BREAK 
commands, and monitoring execution with the SHOW CALLS, SET TRACE, 
and SET WATCH commands 


e Examining and manipulating data with the EXAMINE, DEPOSIT, and 
EVALUATE commands 


¢ Controlling symbol references with path names and the SET MODULE and 
SET SCOPE commands 


Several examples are language specific. However, the general concepts are 
readily adaptable to all supported languages. 


The sample debugging session in Section 2.3 illustrates how to use some of this 
information to locate an error and correct it. 


2.2.1. Compiling and Linking a Program to Prepare for Debugging 


Before you can use the debugger, you must compile and link the modules 
(compilation units) of your program as explained in this section. The following 
example shows how to compile and link a FORTRAN program, consisting of a 
single compilation unit named FORMS, before using the debugger. 


Note 


The /DEBUG and /NOOPTIMIZE qualifiers are compiler command 
defaults for some languages. These qualifiers are used in the example for 
emphasis. 


$ FORTRAN/DEBUG/NOOPTIMIZE FORMS 
$ LINK/DEBUG FORMS 


The /DEBUG qualifier on the compiler command (FORTRAN in this case) directs 
the compiler to write the symbol information associated with FORMS into the 
object module, FORMS.OBJ, in addition to the code and data for the program. 
This symbol information enables you to use the names of variables and other 
symbols declared in FORMS with debugger commands. If your program has 
several compilation units, you must compile each unit whose symbols you want to 
reference with the /DEBUG qualifier. 


Some compilers optimize the object code to reduce the size of the program or 

to make it run faster. In such cases you should compile your program with the 
/NOOPTIMIZE command qualifier (or equivalent) when preparing for debugging. 
Otherwise, the contents of some program locations might be inconsistent with 
what you would expect from viewing the source code. (After the program has 
been debugged, you will probably want to recompile it without the /NOOPTIMIZE 
qualifier to take advantage of optimization.) 


The /DEBUG qualifier on the LINK command directs the linker to include all 
symbol information that is contained in FORMS.OBJ in the executable image. 
The qualifier also causes the VMS image activator to start the debugger at run 
time. If your program has several object modules, you need to specify those 
modules in the LINK command, for most languages. 
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2.2.2 Establishing the Debugging Configuration 


Before invoking the debugger as explained in Section 2.2.3, check that the 
debugging configuration is appropriate for the kind of program you are going to 
debug. 


You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or several 
processes, respectively. The configuration depends on the current definition of 
the logical name DBG$PROCESS. Thus, before invoking the debugger, enter the 
DCL command SHOW LOGICAL DBG$PROCESS to determine the definition of 
DBG$PROCESS. 


Most of this chapter covers programs that run in only one process. For such 
programs, DBG$PROCESS either should be undefined, as in the following 
example, or should have the value DEFAULT: 


S$ SHOW LOGICAL DBGSPROCESS 
SSHOW-S-NOTRAN, no translation for logical name DBGS$PROCESS 


If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 


$ DEFINE DBGSPROCESS DEFAULT 


For more information about multiprocess debugging, see Chapter 10. 


2.2.3 Invoking the Debugger 


After you compile and link your program and establish the appropriate debugging 
configuration, you can then invoke the debugger. To do so, enter the DCL 
command RUN, specifying the executable image of your program as the 
parameter. The following example shows how the debugger identifies itself 

after you invoke it: 


$ RUN FORMS 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is FORTRAN, module set to FORMS 
DBG> 


The diagnostic message that is displayed at debugger startup indicates that this 
debugging session is initialized for a FORTRAN program and that the name of 
the main program unit (the module containing the image transfer address) is 
FORMS. The initialization sets up language-dependent debugger parameters. 


At this point, execution is suspended at the beginning of the main program. 
The DBG> prompt, which is displayed whenever the debugger suspends 
execution, indicates that you can now enter debugger commands, as explained in 
Section 2.2.6. 


2.2.4 Ending a Debugging Session 
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To end a debugging session and return to DCL level, type EXIT or press Ctrl/Z: 
DBG> EXIT 
$ 


The following message, displayed during a debugging session, indicates that your 
program has completed normally: 


SDEBUG-I-EXITSTATUS, is ‘SSYSTEM-S-NORMAL, normal successful completion’ 
DBG> 
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If you want to continue debugging after seeing this message, type EXIT and start 
a new debugging session with the DCL RUN command. You could also restart 
execution from within the debugging session with a command such as GO %LINE 
1. However, this can produce unexpected results if, for example, some variables 
have different values from when you first ran the program. 


2.2.5 Interrupting Program Execution and Aborting Debugger Commands 


If your program goes into an infinite loop during a debugging session so that 
the debugger prompt does not reappear, press Ctrl/C. This interrupts program 
execution and returns you to the debugger prompt (pressing Ctrl/C does not end 
the debugging session). For example: 


DBG> GO 


DBG> 


You can also press Ctrl/C to abort the execution of a debugger command. This is 
useful if a command takes a long time to complete. 


Pressing Ctrl/C when the program is not running or when the debugger is not 
performing an operation has no effect. 


If your program already has a Ctrl/C AST service routine enabled, use the 
SET ABORT_KEY command to assign the debugger’s abort function to another 
Ctrl-key sequence. 


Pressing Ctrl/Y from within a debugging session has the same effect as pressing 
Ctrl/Y during the execution of a program. Control is returned to the DCL 
command interpreter ($ prompt). 


2.2.6 Entering Debugger Commands 


You can enter debugger commands any time you see the debugger prompt 
(DBG>). To enter a command, type it at the keyboard and press RETURN. See 
Section 1 of the command dictionary for complete rules on entering debugger 
commands. 


To obtain online help about debugger commands and specific subjects, proceed as 
follows: 


¢ To list the help topics, enter the HELP command. 

e For an explanation of the help system, enter the command HELP HELP. 
For example: 

¢ To display help about the STEP command, enter the command HELP STEP. 


¢ To display help about debugger diagnostic messages, enter the command 
HELP MESSAGES. 


Section 2 of the command dictionary explains the general format and severity 
levels of debugger diagnostic messages. To obtain online help about a debugger 
message, use the following general command format: 


HELP MESSAGES message-identifier 
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For example, to display information about the message whose identifier is 
NOSYMBOL, enter the following command: 


DBG> HELP MESSAGES NOSYMBOL 


When you invoke the debugger, a few commonly used command sequences are 
automatically assigned to the keys on the numeric keypad (to the right of the 
main keyboard). Thus, you can perform certain functions either by typing a 
command or by pressing a keypad key. 


The predefined key functions are identified in Figure 2-1. 


Most keypad keys have three predefined functions—DEFAULT, GOLD, and 
BLUE. 


¢ To enter a key’s DEFAULT function, press the key. 


¢ To enter its GOLD function, first press and release the PF1 (GOLD) key, and. 
then press the key. 


¢ To enter its BLUE function, first press and release the PF4 (BLUE) key, and 
then press the key. 


In Figure 2-1, the DEFAULT, GOLD, and BLUE functions are listed within each 


key’s outline, from top to bottom, respectively. For example: 

¢ Pressing keypad key KPO enters the STEP command. 

¢ Pressing the PF1 key and then KPO enters the STEP/INTO command. 
¢ Pressing the PF4 key and then KPO enters the STEP/OVER command. 


Normally, keys KP2, KP4, KP6, and KP8 scroll screen displays down, left, 
right, or up, respectively. By putting the keypad in the MOVE, EXPAND, 

or CONTRACT state, indicated in Figure 2-1, you can also use these keys to 
move, expand, or contract displays in four directions. Enter the HELP KEYPAD 
command to display the keypad key definitions. 


You can redefine keypad key functions with the DEFINE/KEY command. 


2.2.7 Displaying Source Code 


The debugger provides two modes for displaying information: noscreen mode and 
screen mode. By default, when you invoke the debugger, you are in noscreen © 
mode, but you might find that it is easier to view source code in screen mode. The 
following sections briefly describe both modes. 


2.2.7.1 Noscreen Mode 
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Noscreen mode is the default, line-oriented mode of displaying input and output. 
The interactive examples throughout this chapter, excluding Section 2.2.7.2, 
illustrate noscreen mode. 


In noscreen mode, use the TYPE command to display one or more source lines. 
For example, the following command displays line 7 of the module in which 
execution is currently suspended: 


DBG> TYPE 7 
module SWAP_ROUTINES 

73 TEMP := A; 
DBG> 
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Figure 2-1 Keypad Key Functions Predefined by the Debugger—Command Interface 
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The display of source lines is independent of program execution. To display source 
code from a module other than the one in which execution is currently suspended, 
use the TYPE command with a path name to specify the module. For example, 
the following command displays lines 16 to 21 of module TEST: 


DBG> TYPE TEST\16:21 


Path names are discussed in more detail in Section 2.2.8.1, in conjunction with 
the STEP command. 


You can also use the EXAMINE/SOURCE command to display the source line for 
a routine or any other program location that is associated with an instruction. 


Note that the debugger also displays source lines automatically when it suspends 
execution at a breakpoint or watchpoint or after a STEP command, or when a 
tracepoint is triggered (see Section 2.2.8). 


After displaying source lines at various locations in your program, you can 
redisplay the location at which execution is currently suspended by pressing 
keypad key KP5. 


If the debugger cannot locate source lines for display, it issues a diagnostic 
message. Source lines might not be available for a variety of reasons. For 
example: 


¢ Execution is suspended within a module that was compiled or linked without 
the /DEBUG qualifier. 


e¢ Execution is suspended within a system or shareable image routine for which 
no source code is available. 


¢ The source file was moved to a different directory after it was compiled (the 
location of source files is embedded in the object modules). In this case, use 
the SET SOURCE command to specify the new location. 


¢ The module might need to be "set" with the SET MODULE command. 
Module setting is explained in Section 2.2.10.1. 


To invoke noscreen mode from screen mode, press the keypad key sequence 
GOLD-PFS (or type SET MODE NOSCREEN). Note that you can use the TYPE 
and EXAMINE/SOURCE commands in screen mode as well as noscreen mode. 


2.2.7.2 Screen Mode 


Screen mode provides the easiest way to view your source code. To invoke screen 
mode, press the PF3 key (or type SET MODE SCREEN). In screen mode, by 
default the debugger splits the screen into three displays named SRC, OUT, and 
PROMPT, as illustrated in Figure 2-2. 
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Figure 2-2 Default Screen Mode Display Configuration 











SRC: module SWAP_ROUTINES— scroll-source 
2: with Text IO; use TEXT IO; 
3: package body SWAP ROUTINES is 
4: procedure SWAPI (A,B: in out INTEGER) is 
5: TEMP: INTEGER; 
6: begin 
7 TEMP := A; 
—> 8 A ; 
9: B: 
10: end; 
11; 
12: procedure SWAP2 (A,B: in out COLOR) is 
— OUT~output 
stepped to SWAP_ROUTINES\SWAP1\%LINE 8 
SWAP_ROUTINES\SWAP1\A: 35 


v 
TEMP ; 


ti 





— PROMPT— error-program-prompt 
DBG> STEP 

DBG> EXAMINE A 

DBG> 
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The SRC display shows the source code of the module in which execution is 
currently suspended. An arrow in the left column points to the source line 
corresponding to the current value of the program counter (PC). The PC is a VAX 
register that contains the memory address of the instruction to be executed next. 
The line numbers, which are assigned by the compiler, match those in a listing 
file. As you execute the program, the arrow moves down and the source code is 
scrolled vertically to center the arrow in the display. 


The OUT display captures the debugger’s output in response to the commands 
that you enter. The PROMPT display shows the debugger prompt, your input (the 
commands that you enter), debugger diagnostic messages, and program output. 


Both SRC and OUT are scrollable so you can see whatever information might 
scroll beyond the display window’s edge. Use keypad key KP3 to select the 
display to be scrolled (by default, SRC is scrolled). Use keypad key KP8 to 
scroll up and keypad key KP2 to scroll down. Scrolling a display does not affect 
program execution. 


In screen mode, if the debugger cannot locate source lines for the routine in 
which execution is currently suspended, it tries to display source lines in the 
next routine down on the call stack for which source lines are available. If the 
debugger can display source lines for such a routine, it issues the following 
message: 


SDEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 
Displaying source in a caller of the current routine. 
DBG> 


In such cases, the arrow in the SRC display identifies the line that contains code 
following the call statement in the calling routine. 
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2.2.8 Controlling and Monitoring Program Execution 


This section explains how to perform the following tasks: 

e Start and resume program execution 

¢ Execute the program to the next source line, instruction, or other step unit 
¢ Determine where execution is currently suspended 

e Use breakpoints to suspend program execution at points of interest 


¢ Use tracepoints to trace the execution path of your program through specified 
locations 


e Use watchpoints to monitor changes in the values of variables 


With this information you can pick program locations where you can then test 
and manipulate the contents of variables as described in Section 2.2.9. 


2.2.8.1 Starting or Resuming Program Execution 
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Use the GO command to start or resume program execution. 


After it is started with the GO command, program execution continues until one 
of the following events occurs: 


¢ The program completes execution 
e A breakpoint is reached 

e A watchpoint is activated 

e An exception is signaled 

¢ You press Ctri/C 


With most programming languages, when you invoke the debugger, execution is 
initially suspended directly at the beginning of the main program. Entering a 
GO command at this point quickly enables you to test for an infinite loop or an 
exception. 


If an infinite loop occurs during execution, the program does not terminate, so the 
debugger prompt does not reappear. To obtain the prompt, interrupt execution 
by pressing Ctrl/C (see Section 2.2.5). If you are using screen mode, the pointer 
in the source display indicates where execution stopped. You can also use the 
SHOW CALLS command to identify the currently active routine calls on the call 
stack (see Section 2.2.8.3). 


If an exception that is not handled by your program is signaled, the debugger 
interrupts execution at that point so that you can enter commands. You can then 
look at the source display and a SHOW CALLS display to find where execution is 
suspended. 


The most common use of the GO command is in conjunction with breakpoints, 
tracepoints, and watchpoints, as described in Section 2.2.8.4, Section 2.2.8.5, 
and Section 2.2.8.6, respectively. If you set a breakpoint in the path of execution 
and then enter the GO command, execution is suspended at that breakpoint. 
Similarly, if you set a tracepoint, execution is monitored through that tracepoint. 
And if you set a watchpoint, execution is suspended when the value of the 
"watched" variable changes. 
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2.2.8.2 Executing the Program by Step Unit 
Use the STEP command to execute the program one or more step units at a time. 


By default, a step unit is one line of source code. In the following example, the 


STEP command executes one line, reports the action ("stepped to... "), and 
displays the line number (27) and source code of the line to be executed next: 
DBG> STEP 


stepped to TEST\COUNT\SLINE 27 
206 - Kee XFS 
DBG> 


Execution is now suspended at the first machine code instruction for line 27 of 
module TEST. Line 27 is in COUNT, a routine within module TEST. 


When displaying a program symbol (for example, a line number, routine name, or 
variable name), the debugger always uses a path name. A path name consists 
of the symbol plus a prefix that identifies the symbol’s location. In the preceding 
example, the path name is TEST\ COUNT\ @LINE 27. The leftmost element of 
a path name is the module name. Moving toward the right, the path name lists 
any successively nested routines and blocks that enclose the symbol. A backslash 
character (\ ) is used to separate elements (except when the language is Ada, 
where a period is used, to parallel Ada syntax). 


A path name uniquely identifies a symbol of your program to the debugger. In 
general, you need to use path names in commands only if the debugger cannot 
resolve a symbol ambiguity in your program (see Section 2.2.10). Usually the 
debugger can determine the symbol you mean from its context. 


When using the STEP command, note that only those source lines for which code 
instructions were generated by the compiler are recognized as executable lines by 
the debugger. The debugger skips over any other lines—for example, comment 
lines. 


You can specify different stepping modes, such as stepping by instruction rather 
than by line (SET STEP INSTRUCTION). Also, by default, the debugger steps 
"over" called routines—execution is not suspended within a called routine, 
although the routine is executed. By entering the SET STEP INTO command, 
you direct the debugger to suspend execution within called routines as well as 
within the routine in which execution is currently suspended (SET STEP OVER 
is the default mode). 


2.2.8.3 Determining Where Execution Is Suspended 


The SHOW CALLS command is useful when you are unsure where execution is 
suspended during a debugging session (for example, after a Ctrl/C interruption). 


The command displays a traceback that lists the sequence of calls leading to 
the routine in which execution is suspended. For each routine (beginning with 
the one in which execution is suspended), the debugger displays the following 
information: 


e The name of the module that contains the routine 
e¢ The name of the routine 


-@ The line number at which the call was made (or at which execution is 
suspended, in the case of the current routine) 


¢ The corresponding PC values (the relative PC address from the beginning of 
the routine and the absolute PC address of the program) 
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For example: 
DBG> SHOW CALLS 


module name routine name line rel PC abs PC 

*TEST PRODUCT 18: 00000009 0000063C 
*TEST COUNT 47. 00000009 00000647 
*MY PROG MY PROG 21 0000000D 00000653 
DBG> 


This example indicates that execution is suspended at line 18 of routine 
PRODUCT (in module TEST), which was called from line 47 of routine COUNT 
(in module TEST), which was called from line 21 of routine MY_PROG (in module 
MY_PROG). 


2.2.8.4 Suspending Program Execution with Breakpoints 
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The SET BREAK command enables you to select locations at which to suspend 
program execution (breakpoints). You can then enter commands to check the call 
stack, examine the current values of variables, and so on. You resume execution 
from a breakpoint with the GO or STEP commands. 


The following example shows a typical use of the SET BREAK command: 


DBG> SET BREAK COUNT 
DBG> GO 


break at routine PROG2\COUNT 
54: procedure COUNT (X,Y: INTEGER) ; 
DBG> 


In the example, the SET BREAK command sets a breakpoint on routine COUNT 
(at the beginning of the routine’s code); the GO command starts execution; 
when routine COUNT is encountered, execution is suspended, the debugger 
announces that the breakpoint at COUNT has been reached ("break at... "), 
displays the source line (54) at which execution is suspended, and prompts for 
another command. At this breakpoint, you could use the STEP command to step 
through routine COUNT and then use the EXAMINE command (discussed in 
Section 2.2.9.1) to check on the values of X and Y. | 


When using the SET BREAK command, you can specify program locations using 
various kinds of address expressions (for example, line numbers, routine 
names, memory addresses, byte offsets). With high level languages, you typically 
use routine names, labels, or line numbers, possibly with path names to ensure 
uniqueness. 


Routine names and labels should be specified as they appear in the source code. 
Line numbers can be derived from either a source code display or a listing file. 
When specifying a line number, use the prefix LINE. Otherwise the debugger 
interprets the line number as a memory location. For example, the next command 
sets a breakpoint at line 41 of the module in which execution is suspended. The 
breakpoint causes the debugger to suspend further execution when the PC value 
is at the beginning of line 41. 


DBG> SET BREAK SLINE 41 


Introduction to the Debugger: Command Interface 
2.2 Getting Started with the Debugger 


Note that you can set breakpoints only on lines that resulted in machine code 
instructions. The debugger warns you if you try to do otherwise (for example on 
a comment line). To pick a line number in a module other than the one in which 
execution is suspended, you must specify the module’s name in a path name. For 
example: 


DBG> SET BREAK SCREEN IO\%LINE 58 


You can also use the SET BREAK command with a qualifier, but no parameter, to 
break on every line, or on every CALL instruction, and so on. For example: 


DBG> SET BREAK/LINE 
DBG> SET BREAK/CALL 


You can set breakpoints on events, such as exceptions, or state transitions in 
tasking programs. 


You can conditionalize a breakpoint (with a "WHEN" clause) or specify that a list 
of commands be executed at the breakpoint (with a "DO" clause). 


To display the currently active breakpoints, enter the SHOW BREAK command. 


To cancel a breakpoint, enter the CANCEL BREAK command, specifying the 
program location exactly as you did when setting the breakpoint. CANCEL 
BREAK/ALL cancels all breakpoints. 


2.2.8.5 Tracing Program Execution with Tracepoints 


The SET TRACE command enables you to select locations for tracing the 
execution of your program (tracepoints), without stopping its execution. After 
setting a tracepoint, you can start execution with the GO command and then 
monitor the path of execution, checking for unexpected behavior. By setting a 
tracepoint on a routine, you can also monitor the number of times it is called. 


As with breakpoints, every time a tracepoint is reached, the debugger issues a 
message and displays the source line. But the program continues executing, and 
the debugger prompt is not displayed. For example: 
DBG> SET TRACE COUNT 
DBG> GO 
trace at routine PROG2\COUNT 

54: procedure COUNT (X,Y: INTEGER) ; 


This is the only difference between a breakpoint and a tracepoint. When using 
the SET TRACE command, you specify address expressions, qualifiers, and 
optional clauses exactly as with the SET BREAK command. 


2.2.8.6 Monitoring Changes in Variables with Watchpoints 


The SET WATCH command enables you to specify program variables that the 
debugger monitors as your program executes. This process is called setting 
watchpoints. If the program modifies the value of a "watched" variable, the 
debugger suspends execution and displays information. The debugger monitors 
watchpoints continuously during program execution. (Note that the SET WATCH 
command can also be used to monitor arbitrary program locations, not just 
variables.) 
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To set a watchpoint on a variable, specify the variable’s name with the SET 
WATCH command. For example, the following command sets a watchpoint on the 
variable TOTAL: 


DBG> SET WATCH TOTAL 


Subsequently, every time the program modifies the value of TOTAL, the 
watchpoint is triggered. 


The next example shows what happens when your program modifies the contents 
of a watched variable. 


DBG> SET WATCH TOTAL 
DBG> GO 


watch of SCREEN_IO\TOTAL at SCREEN _IO\%LINE 13 
13: TOTAL := TOTAL + 1; 
old value: 16 
new value: 17 
break at SCREEN IO\$LINE 14 
14: POP (TOTAL) ; 
DBG> 


In this example, a watchpoint is set on the variable TOTAL and execution is 
started. When the value of TOTAL changes, execution is suspended. The 
debugger announces the event ("watch of... "), identifying where TOTAL 
changed (the beginning of line 13) and the associated source line. The debugger 
then displays the old and new values and announces that execution has been 
suspended at the beginning of the next line (14). Finally, the debugger prompts 
for another command. Note that when a change in a variable occurs at a point 
other than the beginning of a source line, the debugger gives the line number 
plus the byte offset from the beginning of the line. 


The technique previously described for setting watchpoints always applies to 
static variables. A static variable is associated with the same memory address 
throughout program execution. 


A variable that is allocated on the stack or in a register (a nonstatic variable) 
exists only when its defining routine is active (on the call stack). If you try to set 
a watchpoint on a nonstatic variable when its defining routine is not active, the 
debugger issues a warning: 


DBG> SET WATCH Y 
SDEBUG-W-SYMNOTACT, nonstatic variable 'Y’ is not active 
DBG> 


A convenient technique for setting a watchpoint on a nonstatic variable is to 

set a tracepoint on the defining routine, also specifying a DO clause to set the 
watchpoint whenever execution reaches the tracepoint. In the following example, 
a watchpoint is set on the nonstatic variable Y in routine ROUTS. After the 
tracepoint is triggered, the WPTTRACE message indicates that the nonstatic 
watchpoint is set. And the watchpoint is triggered when the value of Y changes: 
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DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y) 
DBG> GO 


trace at routine MOD4\ROUT3 
SDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every 
instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\S%LINE 16 


16: Y := 4 
old value: 3 
new value: 4 
break at MOD4\ROUT3\%LINE 17 
17: SWAP (X,Y); 
DBG> 


When execution returns to the calling routine, the nonstatic variable is no 
longer active, so the debugger automatically cancels the watchpoint and issues a 
message to that effect. 


2.2.9 Examining and Manipulating Program Data 


This section explains how to use the EXAMINE, DEPOSIT, and EVALUATE 
commands to display and modify the contents of variables and evaluate 
expressions. Note that before you can examine or deposit into a nonstatic 
variable, as defined in Section 2.2.8.6, its defining routine must be active (on the 
call stack). 


2.2.9.1 Displaying the Value of a Variable 


To display the current value of a variable, use the EXAMINE command. It has 
the following form: 


EXAMINE variable-name 


The debugger recognizes the compiler-generated data type of the variable you 
specify and retrieves and formats the data accordingly. The following examples 
show some uses of the EXAMINE command. 


Examine a string variable: 


DBG> EXAMINE EMPLOYEE NAME 
PAYROLL\EMPLOYEE NAME: "Peter C. Lombardi" 
DBG> 


Examine three integer variables: 


DBG> EXAMINE WIDTH, LENGTH, AREA 
SIZE\WIDTH: 4 

SIZE\LENGTH: 7 

SIZE\AREA: 28 

DBG> 
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Examine a two-dimensional array of real numbers (three per dimension): 


DBG> EXAMINE REAL ARRAY 
PROG2\REAL_ARRAY 


(1,1): 27.01000 

Oe ae 31.00000 

(15.3) 12.48000 

(2,1) 15.08000 

(2,2): 22.30000 

(2,3): 18.73000 
DBG> 


Examine element 4 of a one-dimensional array of characters: 


DBG> EXAMINE CHAR ARRAY (4) 
PROG2\CHAR_ARRAY (4): ’m’ 
DBG> 


Examine a record variable (COBOL example): 
DBG> EXAMINE PART 


INVENTORY \PART: 
ITEM: "WF-1247" 
PRICE: 49.95 
IN STOCK: 24 

DBG> — 


‘Examine a record component (COBOL example): 


DBG> EXAMINE IN STOCK OF PART 

INVENTORY \IN-STOCK of PART: 
IN STOCK: 24 

DBG> 


Note that the EXAMINE command can be used with any kind of address 
expression (not just a variable name) to display the contents of a program 
location. The debugger associates certain default data types with untyped 
locations. You can override the defaults for typed and untyped locations if you 
want the data interpreted and displayed in some other data format. 


2.2.9.2 Assigning a Value to a Variable 
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To assign a new value to a variable, use the DEPOSIT command. It has the 
following form: 


DEPOSIT variable-name = value 


The DEPOSIT command is like an assignment statement in most programming 
languages. 


In the following examples, the DEPOSIT command assigns new values to 
different variables. The debugger checks that the value assigned, which can 
be a language expression, is consistent with the data type and dimensional 
constraints of the variable. 


Deposit a string value (it must be enclosed in quotation marks (") or apostrophes 
("): 

DBG> DEPOSIT PART NUMBER = "WG-7619.3-84" 

Deposit an integer expression: 

DBG> DEPOSIT WIDTH = CURRENT WIDTH + 10 
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Deposit element 12 of an array of characters (you cannot deposit an entire array 
aggregate with a single DEPOSIT command, only an element): 


DBG> DEPOSIT C_ ARRAY (12) := ‘K’ 


Deposit a record component (you cannot deposit an entire record aggregate with a 
single DEPOSIT command, only a component): 


DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 
Deposit an out-of-bounds value (X was declared as a positive integer): 


DBG> DEPOSIT X = -14 
SDEBUG-I-IVALOUTBNDS, value assigned is out of bounds 
at or near DEPOSIT 


As with the EXAMINE command, you can specify any kind of address expression 
(not just a variable name) with the DEPOSIT command. You can override the 
defaults for typed and untyped locations if you want the data interpreted in some 
other data format. 


2.2.9.3 Evaluating Language Expressions 


To evaluate a language expression, use the EVALUATE command. It has the 
following form: 


EVALUATE language-expression 


The debugger recognizes the operators and expression syntax of the currently 
set language. In the following example, the value 45 is assigned to the integer 
variable WIDTH; the EVALUATE command then obtains the sum of the current 
value of WIDTH and 7: 

DBG> DEPOSIT WIDTH := 45 

DBG> EVALUATE WIDTH + 7 


52 
DBG> 


In the next example, the values TRUE and FALSE are assigned to the Boolean 
variables WILLING and ABLE, respectively; the EVALUATE command then 
obtains the logical conjunction of these values: 

DBG> DEPOSIT WILLING := TRUE 

DBG> DEPOSIT ABLE := FALSE 

DBG> EVALUATE WILLING AND ABLE 


False 
DBG> 


2.2.10 Controlling Access to Symbols in Your Program 


To have full access to the symbols that are associated with your program (variable 
names, routine names, source code, line numbers, and so on), you must compile 
and link the program using the /DEBUG qualifier, as explained in Section 2.2.1. 


Under these conditions, the way in which the debugger handles these symbols 
is transparent to you, in most cases. However, the following two areas might 
require action: 


e Setting and canceling modules 


¢ Resolving symbol ambiguities 
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2.2.10.1 Setting and Canceling Modules 


To facilitate symbol searches, the debugger loads symbol information from the 
executable image into a run-time symbol table (RST), where that information can 
be accessed efficiently. Unless symbol information is in the RST, the debugger 
does not recognize or properly interpret the associated symbols. 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 


At debugger startup, only the module containing the image transfer address 
is set. Subsequently, whenever execution of the program is interrupted, the 
debugger sets the module that contains the routine in which execution is 
suspended. This enables you to reference the symbols that should be visible 
at that location. 


If you try to reference a symbol in a module that has not been set, the debugger 
warns you that the symbol is not in the RST. For example: 
DBG> EXAMINE K 


SDEBUG-W-NOSYMBOL, symbol ‘K’ is not in symbol table 
DBG> 


You must then use the SET MODULE command to set the module containing 
that symbol explicitly: 

DBG> SET MODULE MOD3 

DBG> EXAMINE K 


MOD3\ROUT2\K: 26 
DBG> 


The SHOW MODULE command lists the modules of your program and identifies 
which modules are set. 


Note that dynamic module setting can slow the debugger down as more and more 
modules are set. If performance becomes a problem, you can use the CANCEL 
MODULE command to reduce the number of set modules, or you can disable 
dynamic module setting by entering the SET MODE NODYNAMIC command 
(SET MODE DYNAMIC enables dynamic module setting). 


2.2.10.2 Resolving Symbol Ambiguities 
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Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 


In most cases, the debugger resolves symbol ambiguities automatically. First 

it uses the scope and visibility rules of the currently set language. In addition, 
because the debugger permits you to specify symbols in arbitrary modules (to set 
breakpoints and so on), the debugger uses the ordering of routine calls on the call 
stack to resolve symbol ambiguities. 


If the debugger cannot resolve a symbol ambiguity, it issues a message. For 
example: 
DBG> EXAMINE Y 


sDEBUG-W~-NOUNIQUE, symbol ‘Y’ is not unique 
DBG> 
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You can then use a path name prefix to uniquely specify a declaration of the 
given symbol. First, use the SHOW SYMBOL command to identify all path 
names associated with the given symbol (corresponding to all declarations of that 
symbol) that are currently loaded in the RST. Then use the desired path name 
prefix when referencing the symbol. For example: 


DBG> SHOW SYMBOL Y 

data MOD7\ROUT3\BLOCK1\Y 
data MOD4\ROUT2\Y 

DBG> EXAMINE MOD4\ROUT2\Y 
MOD4\ROUT2\Y: 12 

DBG> 


If you need to refer to a particular declaration of Y repeatedly, use the SET 
SCOPE command to establish a new default scope for symbol lookup. Then, 
references to Y without a path name prefix specify the declaration of Y that is 
visible in the new scope. For example: 

DBG> SET SCOPE MOD4\ROUT2 

DBG> EXAMINE Y 


MOD4\ROUT2\Y: 12 
DBG> 


To display the current scope for symbol lookup, use the SHOW SCOPE command. 
To restore the default scope, use the CANCEL SCOPE command. 
2.3 A Sample Debugging Session 


This section walks you through a debugging session with a simple FORTRAN 
program which contains a logic error (see Example 2—1). Compiler-assigned line 
numbers have been added in the example so that you can identify the source lines 
referenced in the discussion. 


Example 2-1 Sample Program SQUARES 


13 INTEGER INARR(20), OUTARR(20) 

2:0 

3 ¢ ---Read the input array from the data file. 

4: OPEN (UNIT=8, FILE='’DATAFILE.DAT’, STATUS=’ OLD’ ) 
ae READ (8,*) N, (INARR(I), I=1,N) 

GEC 

ya © ---Square all non-zero elements and store in OUTARR. 
8: K=0 

9s D0 10 I=1, N 

10% IF(INARR(I) .NE. 0) THEN 

11: OUTARR(K) = INARR(I) **2 

Les ENDIF 

3: 10 CONTINUE 

14: C 

152. ¢ ---Print the squared output values. Then stop. 
163 PRINT 20, K 

ae & 20 FORMAT(’ Number of non-zero elements is’,14) 
18: DO 40 I=1, K 

3 PRINT 30, I, OUTARR(I) 

20: 30 FORMAT(’ Element’,14,’ has value’,I6) 
21: 40 CONTINUE 
22: END 


The program, called SQUARES, performs the following functions: 


1. Reads a sequence of integer numbers from a data file and saves these 
numbers in the array INARR (lines 4 and 5). 
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2. Enters a loop in which it copies the square of each nonzero integer into 
another array OUTARR (lines 8 through 13). 


3. Prints the number of nonzero elements in the original sequence and the 
square of each such element (lines 16 through 21). 


When you run SQUARES, it produces the following output, regardless of the 
number of nonzero elements in the data file: 


$ RUN SQUARES 
Number of non-zero elements is 0 


The error in the program is that variable K, which keeps track of the current 
index into OUTARR, is not incremented in the loop on lines 9 through 13. The 
statement K = K + 1 should be inserted just before line 11. 


Example 2-2 shows how to compile, link, and run the program to invoke the 
debugger, and then how to use the debugger to find the error. Comments, keyed 


‘to the callouts, follow the example. 


Example 2-2 Sample Debugging Session Using Program SQUARES 


$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES 1 ] 

$ LINK/DEBUG SQUARES 

$ SHOW LOGICAL DBG$PROCESS 3] 
SSHOW-S-NOTRAN, no translation for logical name DBGSPROCESS 


$ RUN sqUARES @O 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is FORTRAN, module set to SQUARESSMAIN 
DBG> STEP 4 
stepped to SQUARESSMAIN\SLINE 9 
9: DO 10 I=1, N 
DBG> EXAMINE N,K 


SQUARESSMAIN\N: 9 
SQUARESSMAIN\K: 0 
DBG> STEP 2 
stepped to SQUARES$MAIN\$LINE 11 
11: OUTARR(K) = INARR(I) **2 
DBG> EXAMINE I,K 
SQUARESSMAIN\I: 1 
SQUARESSMAIN\K: 0 


DBG> DEPOSIT K=1 ®@ 

DBG> SET TRACE/SILENT SLINE 11 DO (DEPOSIT K = K + 1) ® 
DBG> GO 

Number of non-zero elements is 4 

Element 1 has value 16 

Element 2 has value 36 

Element 3 has value 9 

Element 4 has value 49 

$DEBUG-I-EXITSTATUS, is ’SYSTEM-S-NORMAL, normal successful completion’ 
DBG> EXIT 

$ EDIT SQUARES.FOR ® 


EO: IF(INARR(I) .NE. 0) THEN 
TL: K=K+1 

as OUTARR(K) = INARR(I) **2 
Los ENDIF 


(continued on next page) 
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Example 2-2 (Cont.) Sample Debugging Session Using Program SQUARES 


$ FORTRAN/DEBUG/NOOPTIMIZE SQUARES @ 
$ LINK/DEBUG SQUARES 
$ RUN SQUARES 


DBG> SET BREAK LINE 12 DO (EXAMINE I,K) ©® 
DBG> co «~@® 


SQUARESSMAIN\I: 1 


SQUARESSMAIN\K: 1 
DBG> GO 

SQUARESSMAIN\I: 2 
SQUARESSMAIN\K: 2 
DBG> GO 

SQUARESSMAIN\I: 4 
SQUARESSMAIN\K: 3 
DBG> 


The following comments apply to the callouts in Example 2-2. Example 2-1 
shows the program that is being debugged. 


@ The /DEBUG qualifier on the FORTRAN command directs the compiler 
to write the symbol information associated with SQUARES into the object 
module, SQUARES.OBJ, in addition to the code and data for the program. 


The /NOOPTIMIZE qualifier disables optimization by the FORTRAN 
compiler, to ensure that the executable code match the source code of the 
program. Debugging optimized code can be confusing because the contents 
of some program locations might be inconsistent with what you would expect 
from viewing the source code. 


@ The /DEBUG qualifier on the LINK command causes the linker to include all 
symbol information that is contained in SQUARES.OBJ in the executable 
image. The qualifier also causes the VMS image activator to start the 
debugger at run time. 


© The debugger can be invoked in either the default configuration or the 
multiprocess configuration, depending on the definition of the logical name 
DBG$PROCESS. In this example, the SHOW LOGICAL DBG$PROCESS 
command shows that DBG$PROCESS is undefined, indicating that the 
default configuration is in effect. This is the correct configuration for a 
program like SQUARES that runs in only one process. 


© The RUN command invokes the debugger (if you have used the (DEBUG 
qualifier with the LINK command). 
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When the debugger is invoked, it displays an informational message and the 

debugger prompt, DBG>. You can now enter debugger commands. Execution 

is initially suspended at the start of the main program unit (line 1 of program 
SQUARES, in this example). 


You decide to test the values of variables N and K after the READ statement 
has been executed and the value 0 has been assigned to K. 


The command STEP 4 executes 4 source lines of the program. Execution is 
now suspended at line 9. Note that the STEP command ignores source lines 
that do not result in executable code; also, by default, the debugger identifies 
the source line at which execution is suspended. 


The command EXAMINE N, K displays the current values of N and K. Their 
values are correct at this point in the execution of the program. 


The command STEP 2 executes the program into the loop that copies and 
squares all nonzero elements of INARR into OUTARR. 


The command EXAMINE I,K displays the current values of J and K. 


I has the expected value, 1. But K has the value 0 instead of 1, which is 
the expected value. Now you can see the error in the program: K should be 
incremented in the loop just before it is used in line 11. 


The DEPOSIT command assigns K the value it should have now: 1. 


The SET TRACE command is now used to patch the program so that the 
value of K is incremented automatically in the loop. The command sets a 
tracepoint that triggers every time execution reaches line 11: 


¢ The /SILENT qualifier suppresses the "trace at" message that would 
otherwise appear each time line 11 is executed. 


¢ The DO clause issues the DEPOSIT K = K + 1 command every time the 
tracepoint is triggered. . 


To test the patch, the GO command starts execution from the current location. 


The program output shows that the patched program works properly. The 
EXITSTATUS diagnostic message shows that the program executed to 
completion. 


The EXIT command ends the debugging session, returning control to DCL 
level. 


The source file is edited to add K = K + 1 after line 10, as shown. (Compiler- 
assigned line numbers have been added to clarify the example.) 


The program is compiled, linked, and executed again under debugger control, 
to check that it runs correctly. 


The SET BREAK command sets a breakpoint that triggers every time line 12 
is executed. The DO clause displays the values of J and K automatically when 
the breakpoint triggers. 


The GO command starts execution. 


At the first breakpoint, the value of K is 1, indicating that the program is 
running correctly so far. Each additional GO command shows the current 
values of J and K. After two GO commands, K is now 38, as expected, but 
note that J is 4. The reason is that one of the INARR elements was zero so 
that lines 11 and 12 were not executed (and K was not incremented) for that 
iteration of the DO loop. This confirms that the program is running correctly. 
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2.4 Debugger Command Summary 


The following sections list all the debugger commands and any related DCL 
commands in functional groupings, along with brief descriptions. During a 
debugging session, you can get online help on all debugger commands and their 


qualifiers by typing HELP. 


2.4.1 Starting and Ending a Debugging Session 


The following commands are used to start, interrupt, and end a debugging 


session: 


RUN’ 
RUN/[NOJDEBUG? 
EXIT, Ctrl/Z 

QUIT 


Ctrl/C 


(SET,SSHOW) ABORT_KEY 


Ctrl/Y-DEBUG' 


ATTACH 


SPAWN 


Invokes the debugger if LINK/DEBUG was 
used 


Controls whether the debugger is invoked 
when the program is executed 


Ends a debugging session, executing all exit 
handlers 


Ends a debugging session without executing 
any exit handlers declared in the program 


Aborts program execution or a debugger 
command without interrupting the debugging 
session 


(Assigns, identifies) the default Ctrl/C abort 
function to another Ctrl-key sequence, 
identifies the Ctrl-key sequence currently 
defined for the abort function 


Interrupts a program that is running without 
debugger control and invokes the debugger 


Passes control of your terminal from the 
current process to another process 


Creates a subprocess, enabling you to execute 
DCL commands without ending a debugging 
session or losing your debugging context 


1 This is a DCL command, not a debugger command. 


2.4.2 Controlling and Monitoring Program Execution 
The following commands are used to control and monitor program execution: 


GO 
STEP 


(SET,SHOW) STEP 


(SET,SSHOW,CANCEL) BREAK 
(SET,SSHOW,CANCEL) TRACE 
(SET,SSHOW,CANCEL) WATCH 
SHOW CALLS 
SHOW STACK 


CALL 


Starts or resumes program execution 


Executes the program up to the next line, 
instruction, or specified instruction 


(Establishes, displays) the default qualifiers 
for the STEP command 


(Sets, displays, cancels) breakpoints 

(Sets, displays, cancels) tracepoints 

(Sets, displays, cancels) watchpoints 
Identifies the currently active routine calls 


Gives additional information about the 
currently active routine calls 


Calls a routine 
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2.4.4 Controlling Type Selection and Radix 


The following commands are used to examine and manipulate data: 


EXAMINE 


SET MODE [NO]JOPERANDS 


DEPOSIT 


EVALUATE 


Displays the value of a variable or the 
contents of a program location 


Controls whether the address and contents of 
the instruction operands are displayed when 
you examine an instruction 


Changes the value of a variable or the 
contents of a program location 


Evaluates a language or address expression 


The following commands are used to control type selection and radix: 


(SET,SHOW,CANCEL) RADIX 


(SET,SSHOW,CANCEL) TYPE 


SET MODE [NO]G_FLOAT 


(Establishes, displays, restores) the radix for 
data entry and display 


(Establishes, displays, restores) the type for 
program locations that are not associated with 
a compiler generated type 


Controls whether double-precision floating- 
point constants are interpreted as G_FLOAT 
or D_FLOAT 


2.4.5 Controlling Symbol Lookup and Symbolization 


The following commands are used to control symbol lookup and symbolization: 
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SHOW SYMBOL 
(SET,SSHOW,CANCEL) MODULE 


(SET,SHOW,CANCEL) IMAGE 


SET MODE [NO]DYNAMIC 


(SET,SSHOW,CANCEL) SCOPE 
SYMBOLIZE 


SET MODE [NO]LINE 


SET MODE [NO]SYMBOLIC 


Displays symbols in your program 


Sets a module by loading its symbol 
information into the debugger’s symbol ane 
identifies, cancels a set module 


Sets a shareable image by loading data 
structures into the debugger’s symbol table, 
identifies, cancels a set image 


Controls whether or not modules and 
shareable images are set automatically when 
the debugger interrupts execution 


(Establishes, displays, restores) the scope for 
symbol lookup 


Converts a memory address to a symbolic 
address expression 


Controls whether program locations are 
displayed in terms of line numbers or routine- 
name + byte offset 


Controls whether program locations are 
displayed symbolically or in terms of numeric 
addresses 
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The following commands are used to control the display of source code: 


TYPE 
EXAMINE/SOURCE 


SEARCH 
(SET,SHOW) SEARCH 


SET STEP [NOJSOURCE 


(SET,SSHOW) MARGINS 
(SET,SHOW,CANCEL) SOURCE 


(SET,SSHOW) MAX_SOURCE_FILES 


2.4.7 Using Screen Mode 


Displays lines of source code 


Displays the source code at the location 
specified by the address expression 


Searches the source code for the specified 
string 


(Establishes, displays) the default qualifiers 
for the SEARCH command 


Enables/disables the display of source code 
after a STEP command has been executed or 
at a breakpoint, tracepoint, or watchpoint 


(Establishes, displays) the left and right 
margin settings for displaying source code 


(Creates, displays, cancels) a source directory 
search list 


(Establishes, displays) the maximum number 
of source files that can be kept open at one 
time (but does not limit the number of source 
files that can be opened) 


The following commands are used to control screen mode and screen displays: 


SET MODE [NO]SCREEN 
DISPLAY 

SCROLL 

EXPAND 

MOVE 

(SHOW,CANCEL) DISPLAY 
(SET,SHOW,CANCEL) WINDOW 


SELECT 
SHOW SELECT 


SAVE 
EXTRACT 


(SET,SSHOW) TERMINAL 


SET MODE [NO]SCROLL 


Ctrl/W 
DISPLAY/REFRESH 


Enables/disables screen mode 
Creates or modifies a display 
Scrolls a display 

Expands or contracts a display 
Moves a display across the screen 
(Identifies, deletes) a display 


(Creates, identifies, deletes) a window 
definition 


Selects a display for a display attribute 


Identifies the displays selected for each of the 
display attributes 


Saves the current contents of a display into 
another display 


Saves a display or the current screen state 
into a file 


(Establishes, displays) the terminal screen 
height and width that the debugger uses when 
it formats displays and other output 


Controls whether an output display is updated 
line by line or once per command 


Refreshes the screen 
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2.4.8 Editing Source Code 


The following commands are used to control source editing from a debugging 


session: 


EDIT 
(SET,SHOW) EDITOR 


2.4.9 Defining Symbols 


Invokes an editor during a debugging session 


(Establishes, identifies) the editor invoked by 
the EDIT command 


The following commands are used to define and delete symbols for addresses, 


commands, or values: 


DEFINE 


DELETE 
(SET,SHOW) DEFINE 


SHOW SYMBOL/DEFINED 


2.4.10 Using Keypad Mode 


Defines a symbol as an address, command, or 
value 


Deletes symbol definitions 


(Establishes, displays) the default qualifier for 
the DEFINE command 


Identifies symbols that have been defined with 
the DEFINE command 


The following commands are used to control keypad mode and key definitions: 


SET MODE [NO]KEYPAD 
DEFINE/KEY 
DELETE/KEY 

SET KEY 

SHOW KEY 


Enables/disables keypad mode 
Creates key definitions 

Deletes key definitions 

Establishes the key definition state 
Displays key definitions 


2.4.11 Using Command Procedures, Log Files, and Initialization Files 


The following commands are used with command procedures and log files: 


@file-spec 
(SET,SHOW) ATSIGN 
DECLARE 


(SET,SHOW) LOG 
SET OUTPUT [NO]JLOG 


SET OUTPUT [NO]JSCREEN_LOG 
SET OUTPUT [NO]VERIFY 


SHOW OUTPUT 
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Executes a command procedure 


(Establishes, displays) the default file 
specification that the debugger uses to search 
for command procedures 


Defines parameters to be passed to command 
procedures 


(Specifies, identifies) the debugger log file 


Controls whether a debugging session is 
logged 


Controls whether, in screen mode, the screen 
contents are logged as the screen is updated 


Controls whether debugger commands are 
displayed as a command procedure is executed 


Identifies the current output options 
established by the SET OUTPUT command 
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The following commands are used to establish conditional and looping structures 


for debugger commands: 


FOR 


IF 
REPEAT 


WHILE 


EXITLOOP 


2.4.13 Debugging Multiprocess Programs 


Executes a list of commands while 
incrementing a variable 


Executes a list of commands conditionally 


Executes a list of commands a specified 
number of times 


Executes a list of commands while a condition 
is true 


Exits an enclosing WHILE, REPEAT, or FOR 
loop 


The following commands are used for debugging multiprocess programs: 


CONNECT 
DEFINE/PROCESS_GROUP 


DO 


SET MODE [NOJINTERRUPT 


(SET,SHOW) PROCESS 


2.4.14 Additional Commands 


Brings a process under debugger control 


Assigns a symbolic name to a list of process 
specifications 


Executes commands in the context of one or 
more processes 


Controls whether execution is interrupted in 
other processes when it is suspended in some 
process 


Modifies the multiprocess debugging 
environment, displays process information 


The following commands are used for miscellaneous purposes: 


(DISABLE,ENABLE,SHOW) AST 


(SET,SSHOW) EVENT_FACILITY 


(SET,SSHOW) LANGUAGE 
SET MODE [NOJSEPARATE 


SET OUTPUT [NO]TERMINAL 


SET PROMPT 
(SET,SHOW) TASK 


(SET,SHOW) VECTOR_MODE 


SHOW EXIT_HANDLERS 


(Disables, enables) the delivery of ASTs in 
the program, identifies whether delivery is 
enabled or disabled 


(Establishes, identifies) the current run-time 
facility for language-specific events 


(Establishes, identifies) the current language 


Controls whether the debugger, when used 
on a workstation running VWS, creates a 
separate window for debugger input and 
output 


Controls whether debugger output, except 
for diagnostic messages, is displayed or 
suppressed 


Specifies the debugger prompt 


Modifies the tasking environment, displays 
task information 


Enables or disables a debugger vector mode 
option, identifies the current vector mode 
option (for vectorized programs). 


Identifies the exit handlers declared in the 
program 
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SHOW MODE Identifies the current debugger modes 
established by the SET MODE command 
(for example, screen mode, step mode) 


SHOW OUTPUT Identifies the current output options 
established by the SET OUTPUT command 

SYNCHRONIZE VECTOR_MODE Forces immediate synchronization between 
the scalar and vector processors (for vectorized 
programs) 
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This chapter describes the options for invoking the debugger and for controlling 
and monitoring program execution while debugging. 


The chapter includes information that is common to all programs. 
¢ See Chapter 10 for additional information specific to multiprocess programs. 


¢ See Chapter 11 for additional information specific to vectorized programs. 


3.1 Starting and Ending a Debugging Session 
This section explains how to do the following: 
¢ Compile and link your program so you can invoke the debugger 


e Start, interrupt, resume, and end a debugging session 


3.1.1 Invoking the Debugger with the DCL RUN Command 


The usual way to invoke the debugger is as follows: 


1. Compile your program using the /DEBUG and /NOOPTIMIZE (or equivalent) 
qualifiers with the DCL compiler command (consult your language 
documentation to determine the compiler command defaults). 


2. Link your program using the /DEBUG qualifier with the DCL command 
LINK. 


3. Use the DCL command SHOW LOGICAL DBG$PROCESS to make sure that 
the value of the logical name DBG$PROCESS is appropriate for the type of 
program you are debugging (see Section 10.2.1): 


¢ If you are debugging a program that runs in only one process, 
DBG$PROCESS should be either undefined or should have the value 
DEFAULT. 


¢ If you are debugging a program that runs in more than one process, 
DBG$PROCESS should have the value MULTIPROCESS. 


4. Execute your program using the DCL RUN command. The debugger initially 
takes control of the program and prompts for commands. 


Note that you cannot run a program under debugger control over a DECnet link. 
Both the image to be debugged and the debugger must reside on the same node. 


The following example illustrates the previous steps with a simple Pascal 
program, INVENTORY, that consists of two compilation units whose source code 
is in two separate files, FORMS.PAS and INVENTORY.PAS. INVENTORY is the 
main program unit. 
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$ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 
$ RUN INVENTORY 


VAX DEBUG Version 5.5 
SDEBUG-I-INITIAL, language is PASCAL, module set to INVENTORY 
DBG> 


When the debugger first takes control, it does the following: 
¢ Displays its banner. 


¢ Sets the language-dependent parameters to the language of the main program 
(the module that contains the image transfer address). The "INITIAL" 
message identifies the language to which the debugging session is initialized 
and the name of the main program (Pascal and INVENTORY, respectively, 
in the previous example). See Section 4.1.8 and Section 4.1.9 for more 
information about language-dependent parameters. 


e Executes any user-defined initialization file (see Section 8.2). 


e Suspends execution at the beginning of the main program. The DBG> 
prompt, which is displayed whenever the debugger suspends execution, 
indicates that you can now enter debugger commands. 


_In some cases the debugger suspends execution before the beginning of the main 


program and displays the following additional message: 
sDEBUG-I-NOTATMAIN, type GO to get to start of main program 


See Section 9.3 for an explanation of this message. 


The effect of the qualifiers used with the compiler command (PASCAL, in this 
example) and the LINK command is as follows. 


The /DEBUG qualifier on the compiler command loads the debugger symbol 
information associated with each compilation unit into its object module. This 
symbol information enables you to use, in debugger commands, the names of 
variables, routines, labels, and other symbols as they appear in the source code. 
By specifying options with the (DEBUG qualifier, you can control the level of 
symbolic information provided (see Section 5.1.1). This qualifier does not affect 
whether the debugger is invoked or how it is invoked. 


Most compilers optimize code to reduce the size of the program and make it 

run faster. For example, invariant expressions are removed from DO loops so 
that they are evaluated only once at run time; also, some memory locations 
might be allocated to different variables at different points in the program. The 
/NOOPTIMIZE (or equivalent) qualifier ensures that the code is not optimized 
and, therefore, that the contents of all program locations are consistent with what 
you would expect from looking at the source code. Section 9.1 describes some of 
the effects of optimization. 


Note also another possible cause of unexpected behavior. The debugger and your 
program share the same address space. In some rare cases, this can cause the 
debugger to affect how your program executes. Section 3.7 explains how the 
debugger controls execution and the possible sources of interference. 


The /DEBUG qualifier on the LINK command provides the following functions: 


¢ Copies the debugger symbol information from the object modules being linked 
into the debug symbol table (DST) and puts the DST in the executable image. 
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e Directs the image activator to pass control to the debugger when you 
subsequently execute the image with the RUN command. 


See Section 5.1.3 for more details on how the LINK command controls symbol 
information. 


Even if you have compiled and linked an image with the /DEBUG command 
qualifier, you can execute that image normally, without it being under debugger 
control. To do so, use the /NODEBUG qualifier on the DCL RUN command. For 
example: 


$ RUN/NODEBUG INVENTORY 


This is convenient for checking your program after you think it is error free. 
But the data required by the debugger still occupies space within the executable 
image. So, when you think your program is correct, you might want to link your 
program again without the /DEBUG qualifier. This creates an image with only 
traceback data in the DST, to use less disk space. 


Table 3-1 summarizes how to control debugger activation by means of LINK and 
RUN command qualifiers. Note that the LINK command qualifiers /[NOJDEBUG 
and /[NOJTRACEBACK affect not only debugger activation but also the level of 
symbol information provided. 


Table 3-1 Controlling Debugger Activation with the LINK and RUN Commands 


LINK Command To Run Program With To Run Program Without Maximum Symbol 
Qualifier Debugger Debugger Information Available’ 
/DEBUG RUN RUN/NODEBUG Full 

/TRACEBACK or RUN/DEBUG RUN Only traceback*® 
/NODEBUG? 

/NOTRACEBACK Cannot RUN None 


1 The level of symbol information available while debugging is controlled both by the compile command qualifier and the 
LINK command qualifier (see Section 5.1). 


2 LINK/TRACEBACK (or LINK/NODEBUG) is a LINK command default. 


3 Traceback information includes compiler-generated line numbers and the names of routines and modules (compilation 

units). This symbol information is used by the VMS traceback condition handler to identify the PC value and the active 

galls wae : one error has occurred. The information is also used by the debugger SHOW CALLS command (see 
ection 2.2.8.3). 


3.1.2 Invoking the Debugger with the DCL DEBUG Command 


You can invoke the debugger while your program is executing freely—for example, 
if you suspect that the program might be in an infinite loop or if you see erroneous 
output. 


To invoke the debugger in this manner, proceed as follows: 


1. Compile and link the program with the (DEBUG command qualifier, as 
described in the previous section (you can also use LINK/TRACEBACK, but 
only traceback symbols are then available while you debug). 


2. Enter the DCL command RUN/NODEBUG to execute the program without 
debugger control. 


3. Press Ctrl/Y to interrupt the executing program. Control then passes to the 
DCL command interpreter. 
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4. Enter the DCL command DEBUG to activate the debugger. It displays 
its banner, sets the language-dependent parameters to the language of 
the module where execution was interrupted, executes any user-defined 
initialization file, and prompts for commands. Usually you will not know 
where execution was interrupted. Enter the SHOW CALLS command to 
identify the current PC value and the sequence of routine calls on the call 
stack (the SHOW CALLS command is described in Section 2.2.8.3). 


For example: 


$ PASCAL/DEBUG/NOOPTIMIZE FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 
$ RUN/NODEBUG INVENTORY 


Interrupt 


$ DEBUG 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is PASCAL, module set to INVENTORY 
DBG> SHOW CALLS 


Interrupting a running program with Ctrl/Y and then invoking the debugger with 
the DEBUG command is useful under the following conditions: 


e Your program is in an infinite loop. 


e §6After entering the RUN/NODEBUG command, you decide that you want 
debugger control. 


¢ You have not specified the /DEBUG command qualifier at compile time, link — 
time, or run time but want to debug your running program. In this case, 
traceback information is the only symbol information available for debugging. 


3.1.3 Ending a Debugging Session 


To end a debugging session in an orderly manner, use the EXIT or QUIT 
commands, or press Ctrl/Z. These commands invoke the debugger exit handlers to 
close log files, restore the screen and keypad states, and so on. 


The EXIT command and Ctrl/Z have the same effect. The QUIT command is like 
the EXIT command or Ctrl/Z, except that the EXIT command and Ctrl/Z also 
execute any exit handlers that are declared in your program; the QUIT command 
does not. 


3.2 Interrupting and Resuming a Debugging Session 


As explained in Section 2.2.5, use Ctrl/C (not Ctrl/Y) to abort the execution 

of a debugger command or to interrupt program execution. This is useful if a 
command takes a long time to complete or your program is in an infinite loop. 
Control is returned to the debugger rather than to the DCL command interpreter. 


The debugger SPAWN and ATTACH commands enable you to interrupt a 
debugging session from the debugger prompt, enter DCL commands, and return 
to the debugger prompt. These commands function essentially like the DCL 
commands SPAWN and ATTACH. 
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Use the debugger command SPAWN to create a subprocess. Use the debugger 
command ATTACH to attach to an existing process or subprocess. 


You can enter the SPAWN command with or without specifying a DCL command 
as parameter. If you specify a DCL command, it is executed in a subprocess 

Gif the DCL command invokes a utility, that utility is invoked in a subprocess). 
Control returns to the debugging session when the DCL command terminates 
(or when you exit the utility). The following example shows spawning the DCL 
command DIRECTORY. 


DBG> SPAWN DIR [JONES.PROJECT2]*.FOR 


SDEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 


The next example illustrates spawning the DCL command MAIL, which invokes 
the MAIL utility: 


DBG> SPAWN MAIL 
MAIL> READ/NEW 


MAIL> EXIT 
SDEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 


If you enter the SPAWN command without specifying a parameter, a subprocess 
is created, and you can then enter DCL commands. Either logging out of the 
subprocess or attaching to the parent process (with the DCL ATTACH command) 
returns you to the debugging session. For example: 


DBG> SPAWN 
'§ RUN PROG2 


$ ATTACH JONES 1 
SDEBUG-I-RETURNED, control returned to process JONES 1 
DBG> 


If you plan to go back and forth several times between your debugging session 
and a spawned subprocess (which might be another debugging session), use the 
debugger ATTACH command to attach to that subprocess. Use the DCL ATTACH 
command to return to the parent process. Because you do not create a new 
subprocess every time you leave the debugger, you use system resources more 
efficiently. 


If you are running two debugging sessions simultaneously, you can define a new 
debugger prompt for one of the sessions with the SET PROMPT command. This 
helps you to differentiate the sessions. 


3.3 Commands Used to Execute the Program 


Only four debugger commands can be used to execute your program: 


GO 

STEP 

CALL 

EXIT (if your program has exit handlers) 
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As indicated in Section 2.2.8.1, GO and STEP are the basic commands for starting 
and resuming program execution. The STEP command is discussed further in 
Section 3.4. 


_ During a debugging session, routines are executed as they are called during the 
execution of a program. The CALL command enables you to arbitrarily call and 
execute a routine that was linked with your program. This command is discussed 
in Section 8.7. 


The EXIT command was discussed in Section 3.1.3, in conjunction with ending a 
debugging session. Because it executes any exit handlers in your program, it is 
also useful for debugging exit handlers (see Section 9.5). 


When using any of these four commands, keep in mind that program execution 
can be interrupted or stopped by any of the following events: 


¢ The program terminates. 
e A breakpoint is reached. 

¢ A watchpoint is activated. 
e An exception is signaled. 
¢ You press Ctrl/C. 


3.4 Executing the Program by Step Unit 


The STEP command (probably the most frequently used debugger command) 
enables you to execute your program in small increments called step units. 


By default, a step unit is an executable line of source code. In the following 
example, the STEP command executes one line, reports the action ("stepped 
to... "), and displays the line number (27) and source code of the next line to be 
executed: . 


DBG> STEP 

stepped to TEST\COUNT\%LINE 27 
27: X 3= X + 1; 

DBG> 


Execution is now suspended at the first machine code instruction for line 27 of 
module TEST. Line 27 is in COUNT, a routine within module TEST. 


The STEP command can also execute several source lines at a time. If you specify 
a positive integer as a parameter, the STEP command executes that number of 
lines. In the following example, the STEP command executes the next three lines: 
DBG> STEP 3 
stepped to TEST\COUNT\%LINE 34 

34: SWAP (X,Y); 
DBG> 


Note that only those source lines for which code instructions were generated by 
the compiler are recognized as executable lines by the debugger. The debugger 

skips over any other lines—for example, comment lines. Also, if a line has more 
than one statement on it, the debugger executes all the statements on that line 
as part of the single step. 


Source lines are displayed by default after stepping if they are available for the 
module being debugged. Source lines are not available if you are stepping in code 
that has not been compiled or linked with the /DEBUG qualifier (for example, 

a shareable image routine). If source lines are available, you can control their 
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display with the SET STEP [NOJSOURCE command and the /[INOJSOURCE 
qualifier of the STEP command. See Chapter 6 for information about how to 
control the display of source code in general and in particular after stepping. 


3.4.1. Changing the STEP Command Behavior 


The default behavior of the STEP command can be altered in the following two 

ways: 

¢ By specifying a STEP command qualifier—for example, STEP 
AINSTRUCTION. 


e By establishing a new default qualifier with the SET STEP command—for 
example, SET STEP INSTRUCTION. 


In the following example, the STEP/INSTRUCTION command executes the 
next instruction rather than the next line (STEP/LINE is the default behavior). 
The debugger displays the source line (10) associated with the new PC value 


(instruction TSTL): 

DBG> STEP/INSTRUCTION 

stepped to SQUARESSMAIN\SLINE 10+4: TSTL W*-164 (R11) [RO] 
10: IF(INARR(I) .NE. 0) THEN 

DBG> 


After the STEP/INSTRUCTION command executes, subsequent STEP commands 
revert to the default behavior. 


In contrast, the SET STEP command enables you to establish new defaults for 
the STEP command. These defaults remain in effect until another SET STEP 
command is entered. For example, the SET STEP INSTRUCTION command 
causes subsequent STEP commands to behave like STEP/INSTRUCTION (SET 
STEP LINE causes subsequent STEP commands to behave like STEP/LINE). 


There is a SET STEP command parameter for each STEP command qualifier. 


You can override the current STEP command defaults for the duration of a single 
STEP command by specifying other qualifiers. Use the SHOW STEP command to 
identify the current STEP command defaults. 


3.4.2 Stepping Into and Over Routines 


By default, when the PC is at a call statement and you enter the STEP command, 
the debugger steps "over" the called routine. Although the routine is executed, 
execution is not suspended within the routine but, rather, on the beginning of 
the line that follows the call statement. When stepping by instruction, execution 
is suspended on the instruction that follows a called routine’s RET (return from 
routine) instruction. 


To step into a called routine when the PC is at a call statement, enter the STEP 
/INTO command. The following example shows how to step into the routine 
PRODUCT, which is called from routine COUNT of module TEST: 


DBG> STEP 
stepped to TEST\COUNT\%LINE 18 
18: AREA := PRODUCT(LENGTH, WIDTH) ; 


DBG> STEP/INTO 
stepped to routine TEST\PRODUCT 

function PRODUCT(X,Y : INTEGER) return INTEGER is 
DBG> 
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To return to the calling routine from any point within the called routine, use the 
STEP/RETURN command. It causes the debugger to step to the RET instruction 
of the routine being executed. A subsequent STEP command brings you back to - 
the statement that follows the routine call. For example: 
DBG> STEP /RETURN 
stepped on return from TEST\PRODUCT\SLINE 11 to TEST\PRODUCT\SLINE 15+4 

156 end PRODUCT; 
-DBG> STEP 
stepped to TEST\COUNT\%LINE 19 

19; LENGTH := LENGTH + 1; 
DBG> 


To step into several routines, enter the SET STEP INTO command to change the 
default behavior of the STEP command from STEP/OVER to STEP/INTO: 


DBG> SET STEP INTO 


As a result of this command, when the PC is at a call statement, a STEP 
command suspends execution within the called routine. If you later want to step 
over routine calls, enter the SET STEP OVER command. 


When SET STEP INTO is in effect, you can qualify the kinds of called routines 
that the debugger is stepping into by specifying any of the following parameters 
with the SET STEP command: 


e [NO]JSB—Controls whether to step into routines called by JSB instructions. 


¢ [NO]JSHARE—Controls whether to step into called routines in shareable 
images. 


¢ [NO]SYSTEM—Controls whether to step into called system routines. 


These parameters make it possible to step into application-defined routines and 
automatically step over system routines, and so on. For example, the following 
command directs the debugger to step into called routines in user space only. The 
debugger steps over routines in system space and in shareable images. 


DBG> SET STEP INTO, NOSYSTEM, NOSHARE 


3.5 Suspending and Tracing Execution with Breakpoints and 
Tracepoints 


This section discusses use of the SET BREAK and SET TRACE commands to, 
respectively, suspend and trace program execution. The commands are discussed 
together because of their similarities. 


SET BREAK Command Overview 


The SET BREAK command enables you to specify program locations or events at 
which to suspend program execution (breakpoints). After setting a breakpoint, 
you can start or resume program execution with the GO command, letting 

the program run until the specified location or condition is reached. When 

the breakpoint is triggered, the debugger suspends execution, identifies the 
breakpoint, and displays the DBG> prompt. You can then enter debugger 
commands—for example, to determine where you are (with the SHOW CALLS 
command), step into a routine, examine or modify variables, and so on. 


The syntax of the SET BREAK command is as follows: 


SET BREAK{/qualifier{ . . . ]] [address-expression[, .. . ]] 
[WHEN (conditional-expression)| | 
[DO (command; . . . ])] 
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The following example shows a typical use of the SET BREAK command and 
illustrates the general default behavior of the debugger at a breakpoint. 


In this example, the SET BREAK command sets a breakpoint on routine COUNT 
(at the beginning of the routine’s code). The GO command starts execution. When 
routine COUNT is encountered, execution is suspended, the debugger announces 
that the breakpoint at COUNT has been reached ("break at ... "), displays the 
source line (54) where execution is suspended, and prompts for another command: 


DBG> SET BREAK COUNT 
DBG> GO 


break at routine PROG2\COUNT 
54: procedure COUNT (X,Y: INTEGER) ; 
DBG> 


SET TRACE Command Overview 

The SET TRACE command enables you to select program locations or events for 
tracing the execution of your program without stopping its execution (tracepoints). 
After setting a tracepoint, you can start execution with the GO command and 
then monitor that location, checking for unexpected behavior. By setting a 
tracepoint on a routine, you can also monitor the number of times it is called. 


The debugger’s default behavior at a tracepoint is identical to that at a 
breakpoint, except that program execution continues past a tracepoint. Thus, 
the DBG> prompt is not displayed when a tracepoint is reached and announced 
by the debugger. 


Except for the command name, the syntax of the SET TRACE command is 
identical to that of the SET BREAK command: 


SET TRACE[/qualifier, . . . | [address-expressior{, .. . ]] 
[WHEN (conditional-expression)| 
[DO (command; . . . })] 


The SET TRACE and SET BREAK commands have the same qualifiers. When — 
using the SET TRACE command, you specify address expressions, qualifiers, and 
the optional WHEN and DO clauses exactly as with the SET BREAK command. 


Unless you use the /TEMPORARY qualifier on the SET BREAK (or SET TRACE) 
command, breakpoints (and tracepoints) remain in effect until you cancel them or 
exit the debugging session. 


To identify all of the breakpoints (or tracepoints) that are currently set, use 
the SHOW BREAK (or SHOW TRACE) command. To cancel breakpoints (or 
tracepoints), use the CANCEL BREAK (or CANCEL TRACE) command (see 
Section 3.5.6). | 


The following sections describe how to specify program locations and events with 
the SET BREAK and SET TRACE commands. 
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3.5.1 Setting Breakpoints or Tracepoints on Individual Program Locations 


To set a breakpoint (or a tracepoint) on a particular program location, specify an 
address expression with the SET BREAK (or SET TRACE) command. 


Fundamentally, an address expression specifies a memory address or a VAX 
register. Because the debugger understands the symbols associated with your 
program, the address expressions you typically use with the SET BREAK (or SET 
TRACE) command are routine names, labels, or source line numbers rather than 
memory addresses—the debugger converts these symbols to addresses. 


3.5.1.1 Specifying Symbolic Addresses 
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Note 


In some cases, when using the SET BREAK or SET TRACE command 
with a symbolic address expression, you might need to set a module or 
specify a scope or a path name. Those concepts are described in detail in 
Chapter 5. The examples in this section assume that all modules are set 
and that all symbols referenced are uniquely defined, unless otherwise 
indicated. 


The following examples illustrate how to set a breakpoint (or a tracepoint) on a 
routine (SWAP) and a label (LOOP1): 


DBG> SET BREAK SWAP 
DBG> SET TRACE LOOP1 


The next command sets a breakpoint on the RET (return) instruction of routine 
SWAP. "Breaking" on the RET instruction of a routine enables you to inspect the 
local environment before the RET instruction removes the routine’s call frame 
from the call stack. 


DBG> SET BREAK/RETURN SWAP 


Some languages, for example FORTRAN, use numeric labels. To set a breakpoint 
(or a tracepoint) on a numeric label, you must precede the number with the built- 
in symbol %LABEL. Otherwise, the debugger interprets the number as a memory 
address. For example, the following command sets a tracepoint on label 20. 


DBG> SET TRACE SLABEL 20 


You can set a breakpoint (or a tracepoint) on a line of source code by specifying 
the line number preceded by the built-in symbol %LINE. The following command 
sets a breakpoint on line 14. 


DBG> SET BREAK %SLINE 14 


The preceding breakpoint causes execution to be suspended when the PC value 
is on the first instruction of line 14. Note that you can set a breakpoint (or a 
tracepoint) only on lines for which the compiler-generated instructions (lines that 
resulted in executable code). If you specify a line number that is not associated 
with an instruction, such as a comment line or a statement that declares but does 
not initialize a variable, the debugger issues a diagnostic message. For example: 
DBG> SET BREAK %LINE 6 

SDEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 


SDEBUG-E-NOSYMBOL, symbol 'SLINE 6’ is not in the symbol table 
DBG> 


The preceding messages indicate that the compiler did not generate instructions 
for lines 6 or 7 in this case. 
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Some languages, for example BASIC, allow more than one statement on a line. 
In such cases, you can use statement numbers to differentiate among statements 
on the same line. A statement number consists of a line number, followed by a 
period (.) and a number indicating the statement. The format is as follows: 


%LINE line-number.statement-number 


For example, the following command sets a tracepoint on the second statement of 
line 38: 


DBG> SET TRACE SLINE 38.2 


When searching for symbols that you reference in commands, the debugger 

uses the conventions described in Section 5.3.1. That is, it first looks within the 
module where execution is currently suspended, then in other scopes associated 
with routines on the call stack, and so on. Therefore, to specify a symbol that is 
defined in more than one module, such as a line number, you might need to use 
a path name. For example, the following command sets a tracepoint on line 27 of 
module MOD4: 


DBG> SET TRACE MOD4\%LINE 27 


Remember the symbol lookup conventions when specifying a line number in 
debugger commands. If that line number is not defined in the module where 
execution is suspended (because it is not associated with an instruction), the 
debugger uses the symbol lookup conventions to locate another module where the 
line number is defined. 


When specifying address expressions, you can combine symbolic addresses with 
byte offsets. Thus, you can set a breakpoint (or a tracepoint) on a particular 
assembly language instruction by specifying its line number and the byte offset 
from the beginning of that line to the first byte of the instruction. For example, 
the next command sets a breakpoint on the address that is five bytes beyond the 
beginning of line 23. 


DBG> SET BREAK %SLINE 23+5 


3.5.1.2 Specifying Locations in Memory 
To set a breakpoint (or a tracepoint) on a location in memory, specify its numerical 
address in the currently set radix. The default radix for both data entry and 
display is decimal for all languages except BLISS and MACRO. It is hexadecimal 
for BLISS and MACRO. For example, the following command sets a breakpoint at 
address 2753, decimal (for all languages except BLISS or MACRO), or at address 
2753, hexadecimal (for BLISS and MACRO): 


DBG> SET BREAK 2753 
You can specify a radix when you enter an individual integer literal (such as 
2753) by using one of the built-in symbols %BIN, %0CT, %DEC, or %HEX. For 


example, in the following command line the symbol %HEX specifies that 2753 
should be treated as a hexadecimal integer: 


DBG> SET BREAK sHEX 2753 


Note that when specifying a hexadecimal number that starts with a letter rather 
than a number, you must add a leading "0". Otherwise, the debugger tries to 
interpret the entity specified as a symbol declared in your program. 


See Section 4.1.9 and Appendix D for additional information about specifying 
radixes and on the built-in symbols BIN, %DEC, %HEX, and %OCT. 
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If a breakpoint (or a tracepoint) was set on a numerical address that corresponds 
to a symbol in your program, the SHOW BREAK (or SHOW TRACE) command 
identifies the breakpoint symbolically. 


3.5.1.3 Obtaining and Symbolizing Memory Addresses 


Use the EVALUATE/ADDRESS command to determine the memory address 
associated with a symbolic address expression, such as a line number, routine 
name, or label. For example: 


DBG> EVALUATE/ADDRESS SWAP 


1536 
DBG> EVALUATE/ADDRESS %LINE 26 
1629 - 
DBG> 


The address is displayed in the current radix. You can specify a radix qualifier to 
display the address in another radix. For example: . 
DBG> EVALUATE/ADDRESS/HEX %LINE 26 


0000065D 
DBG> 


The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS. It 
converts a memory address into its symbolic representation (including its path 
name) if such a representation is possible. Chapter 5 explains how to control 
symbolization. See Section 4.1.10 for more information about obtaining and 
symbolizing addresses. 


3.5.2 Setting Breakpoints or Tracepoints on Lines or Instructions 
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Several SET BREAK (and SET TRACE) command qualifiers cause the debugger 
to break on (or trace) every source line or every assembly language instruction of 
a particular class: 


/LINE 

/BRANCH 

/CALL 

ANSTRUCTION 
AINSTRUCTION=(opcode[, . . . J) 


When using these qualifiers, do not specify an address expression. 


For example, the following command causes the debugger to break on the 
beginning of every source line encountered during execution: 


DBG> SET BREAK/LINE 


The instruction-related qualifiers are especially useful for opcode tracing, which 
is the tracing of all instructions or the tracing of a class of instructions. The next 
command causes the debugger to trace every branch instruction encountered (for 
example BEQL, BGTR, and so on): 


DBG> SET TRACE/BRANCH 
Note that opcode tracing slows program execution. 


By default, when you use the qualifiers discussed in this section, the debugger 
breaks (or traces) within all called routines as well as within the currently 
executing routine (this is equivalent to specifying SET BREAK/INTO or SET 
TRACE/INTO). By specifying SET BREAK/OVER or SET TRACE/OVER, you can 
suppress break (or trace) action within all called routines. Or, you can use the 
/[NOJJSB, /[NO]SHARE, or /[NOJSYSTEM qualifiers to specify the kinds of called 
routines where break (or trace) action is to be suppressed. For example, the 
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next command causes the debugger to break on every line except within called 
routines that are in shareable images or system space: 


DBG> SET BREAK/LINE/NOSHARE/NOSYSTEM 


3.5.3 Controlling Debugger Action at Breakpoints or Tracepoints 


The SET BREAK and SET TRACE commands provide several options for 
controlling the behavior of the debugger at breakpoints and tracepoints—the 
/AFTER, /[NO]SILENT, /INOJSOURCE, and /TEMPORARY command qualifiers, 
and the optional WHEN and DO clauses. The following examples illustrate 
several of these options. 


The next command sets a breakpoint on line 14 and specifies that the breakpoint 
take effect after the fifth time that line 14 is executed: 


DBG> SET BREAK/AFTER:5 %LINE 14 


The next command sets a tracepoint that is triggered at every line of execution. 
The DO clause obtains the value of the variable X when each line is executed: 


DBG> SET TRACE/LINE DO (EXAMINE X) 


The next example illustrates how the WHEN and DO clauses can be used 
together. The command sets a breakpoint at line 27. The breakpoint is triggered 
(execution is suspended) only when the value of SUM is greater than 100 (not 
each time line 27 is executed). The DO clause causes the value of TEST_RESULT 
to be examined whenever the breakpoint is triggered—that is, whenever the value 
of SUM is greater than 100. If the value of SUM is not greater than 100 when 
execution reaches line 27, the breakpoint is not triggered and the DO clause is 
not executed. . 


DBG> SET BREAK cLINE 27 WHEN (SUM > 100) DO (EXAMINE TEST RESULT) 


See Section 4.1.5 and Section 9.3.2.2 for information about evaluating language 
expressions, such as the expression "SUM > 100". 


The /SILENT qualifier suppresses the break or trace message and source code 
display. This is useful when, for example, you want to use the SET TRACE 
command only to execute a debugger command at the tracepoint. In the next 
example, the SET TRACE command is used to examine the value of the Boolean 
variable STATUS at the tracepoint. 


DBG> SET TRACE/SILENT LINE 83 DO (EXAMINE STATUS) 
DBG> GO 


SCREEN_IO\CLEAR\STATUS: OFF 


In the next example, the SET TRACE command is used to count the number of 
times line 12 is executed. The first DEFINE/VALUE command defines a symbol 
COUNT and initializes its value to zero. The DO clause of the SET TRACE 
command causes the value of COUNT to be incremented and evaluated whenever 
the tracepoint is triggered (whenever execution reaches line 12). 


DBG> DEFINE/VALUE COUNT=0 
DBG> SET TRACE/SILENT %LINE 12 DO (DEF/VAL COUNT=COUNT+1;EVAL COUNT) 
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Source lines are displayed by default at breakpoints, tracepoints, and watchpoints 
if they are available for the module being debugged. You can also control their 
display with the SET STEP [NO]SOURCE command and the /[NOJSOURCE 
qualifier of the SET BREAK, SET TRACE, and SET WATCH commands. See 
Chapter 6 for information about how to control the display of source code in 
general and in particular at breakpoints, tracepoints, and watchpoints. 


3.5.4 Setting Breakpoints or Tracepoints on Exceptions 


The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands direct 
the debugger to treat any exception generated by your program as a breakpoint 
or tracepoint, respectively. The breakpoint (or tracepoint) occurs before any 
application-declared exception handler is invoked. See Section 9.4 for debugging 
techniques associated with exceptions and condition handlers. 


3.5.5 Setting Breakpoints or Tracepoints on Events 
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The SET BREAK and SET TRACE commands each have an /EVENT=event-name 
qualifier. You can use this qualifier to set breakpoints or tracepoints that are 
triggered by various events (denoted by event-name keywords). Events and their 
keywords are currently defined for the following event facilities: 


¢ ADA event facility, which defines VAX Ada tasking events. ADA events are 
defined in Section 12.6.4. 


e THREADS event facility, which defines tasking (multithread) events for 
programs written in any language that use DECthreads services. THREADS 
events are defined in Section 12.6.4. 


¢ SCAN event facility, which defines SCAN pattern-matching events. SCAN 
events are defined in Section E.12.6.1. 


The appropriate facility and event-name keywords are defined at debugger 
startup. Use the SHOW EVENT_FACILITY command to identify the current 
event facility and the associated event-name keywords. The SET EVENT_ 
FACILITY command enables you to change the event facility and thereby change 
your debugging context. This is useful if you have a multilanguage program and 
want to debug a routine that is associated with an event facility but that facility 
is not currently set. 


The following examples briefly illustrate how to set event breakpoints with 
tasking programs and SCAN programs. When a breakpoint or tracepoint is 
triggered, the debugger identifies the event that caused it to be triggered and 
gives additional information. 


- The following command causes the debugger to break whenever any task enters 


the SUSPENDED state. 
DBG> SET BREAK/EVENT=SUSPENDED 
The next command sets two tracepoints, which are associated with the Ada tasks 


CHECKIN and RESERVE, respectively. Each tracepoint is triggered whenever 
its associated task makes a transition to the RUN state. 


DBG> SET TRACE/EVENT=RUN CHECKIN, RESERVE 


The next command causes the debugger to break whenever a SCAN token is 
built, for any value. 


DBG> SET BREAK/EVENT=TOKEN 


See Section 9.3.2 for information about predefined Ada event breakpoints. 
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3.5.6 Canceling Breakpoints or Tracepoints 


Use the CANCEL BREAK and CANCEL TRACE commands to cancel breakpoints 
and tracepoints, respectively. To cancel a breakpoint (or a tracepoint), specify 
address expressions and qualifiers exactly as you specified them when setting the 
breakpoint (or tracepoint). 


Thus, to cancel breakpoints (or tracepoints) that were set at specific address 
expressions, specify those same address expressions. For example: 


DBG> CANCEL BREAK SWAP,MOD2\LOOP4, 2753 


To cancel breakpoints (or tracepoints) that were set with the following command 
qualifiers, specify those same command qualifiers: 


/BRANCH 

/CALL 

/EVENT=event-name 
/EXCEPTION 

AINSTRUCTION 
ANSTRUCTION=(opcode[, ... ]) 
/LINE 


If the qualifier requires one or more keywords, include the keywords associated 
with the breakpoints or tracepoints to be canceled. For example: 
DBG> CANCEL BREAK/LINE 


DBG> CANCEL TRACE/INSTRUCTION=(JSB, CALLS) 
DBG> CANCEL TRACE/EVENT=RUN CHECKIN 


3.6 Monitoring Changes in Variables and Other Program Locations 


The SET WATCH command enables you to specify program variables (or arbitrary 
memory locations) that the debugger monitors as your program executes. This 
process is called setting watchpoints. If, during execution, the program modifies 
the value of a "watched" variable (or memory location), the watchpoint is 
triggered. The debugger then suspends execution, displays information, and 
prompts for more commands. The debugger monitors watchpoints continuously 
during program execution. 


This section describes the general use of the SET WATCH command. Section 3.6.2 
gives additional information pertaining to setting watchpoints on nonstatic 
variables—variables that are allocated on the call stack or in registers. 


Note 


In some cases, when using the SET WATCH command with a variable 
name (or any other symbolic address expression), you might need to set a 
module or specify a scope or a path name. Those concepts are described 
in Chapter 5. The examples in this section assume that all modules are 
set and that all variable names are uniquely defined. 


If your program was optimized during compilation, certain variables in 
the program might be removed by the compiler. If you then try to set 
a watchpoint on such a variable, the debugger issues a warning (see 
Section 9.1). 
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The syntax of the SET WATCH command is as follows: 


SET WATCH[/qualifier| . . . ]] [address-expressior|, . . . ]] 
[WHEN (conditional-expression)| 
[DO (command; .. . ])] 


Although any valid address expression can be specified, usually you specify the 
name of a variable. The example that follows shows a typical use of the SET 
WATCH command and illustrates the general default behavior of the debugger at 
a watchpoint. 


DBG> SET WATCH COUNT 
DBG> GO 


watch of MOD2\COUNT at MOD2\%LINE 24 
24: COUNT := COUNT + 1; 
old value: 27 
new value: 28 
break at MOD2\%LINE 25 
23% END; 
DBG> 


In this example, the SET WATCH command sets a watchpoint on the variable 
COUNT, and the GO command starts execution. When the program changes the 
value of COUNT, execution is suspended. The debugger then does the following: 


e Announces the event ("watch of MOD2\COUNT ... "), identifying the 
location of the instruction that changed the value of the watched variable 
("... at MOD2\ @LINE 24") 


e Displays the associated source line (24) 
¢ Displays the old and new values of the variable (27 and 28) 


e Announces that execution has been suspended at the beginning of the next 
line ("break at MOD2\ %LINE 25") and displays that source line 


¢ Prompts for another command 


When the address of the instruction that modified a watched variable is not at 
the beginning of a source line, the debugger denotes the instruction’s location by 
displaying the line number plus the byte offset from the beginning of the line. 
For example: 


DBG> SET WATCH kK 
DBG> GO 


watch of TEST\K at TEST\%SLINE 19+5 
19: DO 40 K=1, J 
old value: 4 
new value: 5 
break at TEST\%LINE 19+9 
19: DO 40 K=1, J 
DBG> 


In this example, the address of the instruction that modified variable K is 5 bytes 
beyond the beginning of line 19. Note that the breakpoint is on the instruction 
that follows the instruction that modified the variable (not on the beginning of 
the next source line as in the preceding example). 
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You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record triggers if any element of the array or 
record changes. Thus, you do not need to set watchpoints on individual array 
elements or record components. Note, however, that you cannot set an aggregate 
watchpoint on a variant record. In the following example, the watchpoint is 
triggered because element 3 of array ARR was modified: 


DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBR\%SLINE 12 


12: ARR(3) := 28 
old value: 
(1): 7 
(2): 12 
(3): 3 
(4): 0 
new value: 
(1): 7 
(2): EZ 
(3) 3 28 
(4): 0 
break at SUBR\SLINE 13 
DBG> 


You can also set a watchpoint on a record component, on an individual array 
element, or on an array slice (a range of array elements). A watchpoint set on an 
array slice triggers if any element within that slice changes. When setting the 
watchpoint, use the syntax of the current language. For example, the following 
command sets a watchpoint on element 7 of array CHECK using Pascal syntax: 


DBG> SET WATCH CHECK[7] 


To identify all of the watchpoints that are currently set, use the SHOW WATCH 
command. To cancel watchpoints, use the CANCEL WATCH command. 


Note that the SET BREAK/MODIFY and SET WATCH commands have the same 
effect. 


3.6.1 Watchpoint Options 


The SET WATCH command provides the same options for controlling the behavior 
of the debugger at watchpoints that the SET BREAK and SET TRACE commands 
provide for breakpoints and tracepoints—namely the /AFTER, /[NO]JSILENT, 
/LNOJSOURCE, and /TEMPORARY qualifiers, and the optional WHEN and DO 
clauses. See Section 3.5.3 for examples. 


3.6.2 Watching Nonstatic Variables 


Storage for a variable in your program is allocated either statically or 
nonstatically. A static variable is associated with the same memory address 
throughout execution of the program. A nonstatic variable is allocated on 
the call stack or in a register and has a value only when its defining routine is 
active, on the call stack. As explained in this section, the technique for setting 
a watchpoint, the watchpoint’s behavior, and the speed of program execution are 
different for the two kinds of variables. 
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To determine how a variable is allocated, use the EVALUATE/ADDRESS 
command. A static variable generally has its address in PO space (0 to 
3FFFFFFF, hexadecimal). A nonstatic variable generally has its address in 

P1 space (40000000 to 7FFFFFFF, hexadecimal) or is in a register. In the 
following Pascal code example, X is declared as a static variable, whereas Y is a 
nonstatic variable (by default). The EVALUATE/ADDRESS command, entered 
while debugging, shows that X is allocated at memory location 512, whereas Y is 
allocated in register RO: 


VAR 
X: [STATIC] INTEGER; 
Y: INTEGER; 


DBG> EVALUATE/ADDRESS X 
512 

DBG> EVALUATE/ADDRESS Y 
%RO 

DBG> 


When using the SET WATCH command, note the following distinction. You can 
set a watchpoint on a static variable regardless of the PC value when you enter 
the command; but you can set a watchpoint on a nonstatic variable only when 
the PC value is within the routine where that variable is defined. Otherwise, the 
debugger issues a warning. For example: 

DBG> SET WATCH Y 

SDEBUG-W-SYMNOTACT, nonstatic variable ‘MOD4\ROUT3\Y’ 


is not active 
DBG> 


Section 3.6.2.2 describes how to set a watchpoint on a nonstatic variable. 


3.6.2.1 Execution Speed 
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When a watchpoint is set, the speed of program execution depends on whether 
the variable is static or nonstatic. To watch a static variable, the debugger write- 
protects the page containing the variable. If your program attempts to write to 
that page (modify the value of that variable), an access violation occurs and the 
debugger handles the exception. The debugger temporarily unprotects the page 
to allow the instruction to complete and then determines whether the watched 
variable was modified. Except when writing to that page, the program executes 
at full speed. 


Because problems arise if the call stack or registers are write-protected, the 
debugger must use another technique to watch a nonstatic variable. It traces 
every instruction in the variable’s defining routine and checks the value of the 
variable after each instruction has been executed. Because this significantly slows 
down the execution of the program, the debugger issues the following message 
when you set a nonstatic watchpoint: 


DBG> SET WATCH Y 


SDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 
DBG> 
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3.6.2.2 Setting a Watchpoint on a Nonstatic Variable 


To set a watchpoint on a nonstatic variable, make sure that the PC value is 
within the defining routine. A convenient technique is to set a tracepoint on that 
routine, also specifying a DO clause to set the watchpoint. Thus, whenever the 
routine is called, the tracepoint is triggered and the watchpoint is automatically 
set on the local variable. In the following example, the WPTTRACE message 
indicates that a watchpoint has been set on Y, a nonstatic variable that is local to 
routine ROUTS: 


DBG> SET TRACE/NOSOURCE ROUT3 DO (SET WATCH Y) 
DBG> GO 


trace at routine MOD4\ROUT3 
SDEBUG-I-WPTTRACE, nonstatic watchpoint, tracing every instruction 


watch of MOD4\ROUT3\Y at MOD4\ROUT3\%LINE 16 
16: Y:= 4 
old value: 3 
new value: 4 
break at MOD4\ROUT3\%LINE 17 
17: SWAP (X,Y); 
DBG> 


When execution returns to the caller of routine ROUTS, variable Y is no longer 
active. Therefore, the debugger automatically cancels the watchpoint and issues 
the following messages: 


SDEBUG-I-WATCHVAR, watched variable MOD4\ROUT3\Y has gone out of scope 
¢DEBUG-I-WATCHCAN, watchpoint now cancelled 


3.6.2.3 Options for Watching Nonstatic Variables 


The SET WATCH command qualifiers /OVER, /INTO, and /[NOJSTATIC provide 
options for watching nonstatic variables. 


When you set a watchpoint on a nonstatic variable, you can direct the debugger 
to do one of two things at a routine call: 


e Step over the called routine—executing it at full speed—and resume 
instruction tracing after returning. This is the default (SET WATCH/OVER). 


¢ Trace instructions within the called routine, thereby monitoring the variable 
instruction-by-instruction within the routine (SET WATCH/INTO). 


Using the SET WATCH/OVER command results in better performance. But 

it also means that, if the called routine modifies the watched variable, the 
watchpoint is triggered only after execution returns from that routine. The 
SET WATCH/INTO command slows down program execution but enables you to 
monitor watchpoints more precisely within called routines. 


The debugger determines whether a variable is static or nonstatic by looking 

at its address (PO space, P1 space, or register). When entering a SET WATCH 
command, you can override this decision with the /[NOJSTATIC qualifier. For 
example, if you have allocated nonstack storage in P1 space, use the SET WATCH 
/STATIC command to specify that a particular variable is static even though it 

is in P1 space. Conversely, if you have allocated your own call stack in PO space, 
use the SET WATCH/NOSTATIC command to specify that a particular variable is 
nonstatic even though it is in PO space. 
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3.6.2.4 Setting Watchpoints in Installed Writable Shareable Images 


When setting a watchpoint in an installed writable shareable image, use the SET 
WATCH/NOSTATIC command (see Section 3.6.2.3). 


The reason you must set a nonstatic watchpoint is as follows. Variables declared 
in such shareable images are typically static variables. By default, the debugger 
watches a static variable by write-protecting the page containing that variable. 
However, the debugger cannot write-protect a page in an installed writable 
shareable image. Therefore, the debugger must use the slower method of 
detecting changes, as for nonstatic variables—that is, by checking the value at the 
watched location after each instruction has been executed (see Section 3.6.2.1). 


Note that if any other process modifies the watched location’s value, the debugger 
may report that your program modified the watched location. 


3.7 How the Debugger Controls Program Execution 
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This section is for readers who are interested in how the debugger functions. 


The debugger controls and monitors execution by causing exceptions to occur at 
points of interest in your program. For example, it might put a breakpoint fault 
instruction (BPT) in your code, causing a breakpoint exception to occur when that 
instruction is executed. The debugger might also set the trace enable bit (T bit) 
in the processor status longword (PSL), thus causing a trace trap at the end of 
each instruction. 


When you run your program with the debugger, the debugger is the primary 
exception handler. Any exception resulting from the execution of your program, 
whether or not it is caused by the debugger, is first handled by the debugger. 

If the debugger did not cause the exception, it resignals the exception (see 
Section 9.4 for information and debugging techniques related to exceptions and 
condition handlers). If the debugger caused the exception, it takes appropriate 
action. For example, in the case of a tracepoint the debugger identifies the 
tracepoint and returns control to the program. In the case of a breakpoint, the 
debugger maintains control by identifying the breakpoint and then prompting for 
commands. 


The following paragraphs illustrate the functioning of the debugger with 
some typical commands—SET BREAK and STEP. See also Section 3.6.2 and 
Section 9.4 for implementation information about the SET WATCH and SET 
BREAK/EXCEPTION commands, respectively. 


When you set a breakpoint, specifying a particular address expression, the 
debugger removes the opcode at that address and replaces it with the BPT 
instruction. When execution reaches that address, the BPT instruction causes a 
breakpoint fault, which gives control to the debugger: 


1. The debugger announces the breakpoint and prompts for commands. When 
you resume execution, the debugger performs the following steps. 


2. The debugger replaces the original opcode and sets the T bit of the saved PSL 
on the call stack, so that a trace trap occurs when the current instruction is 
executed. 


The instruction is executed. 


4, When the trace trap occurs, the debugger replaces the BPT instruction at 
the original breakpoint address, so that the break fault occurs whenever 
execution again reaches that address. 
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When you enter a STEP/INSTRUCTION command, the debugger sets the T bit of 
the saved PSL, executes the next instruction, then, when the trace trap occurs, 
issues a message and prompts for commands. 


The STEP/LINE command is implemented similarly, except that the debugger 
keeps track of line boundaries by correlating the low and high PC values of each 
line with data stored in the symbol table. The debugger completes the step and 
prompts for commands when you leave the current line. 


When you set a breakpoint on a class of instructions and then start execution, the 
debugger traces (traps on) every instruction by setting the T bit of the saved PSL. 
If the next instruction is of the desired class, the debugger suspends execution on 
that instruction, announces the breakpoint, and prompts for commands. If the 
instruction is not of the desired class, the debugger continues to trace and execute 
instructions. 


‘When you enter a STEP/OVER command at a routine call, the debugger does the 
following: 


1. Steps into the routine, then sets a reserved bit in the saved PSL. 


2. Lets the program run. The routine is executed, but the RET instruction 
causes a reserved-operand exception when it tries to restore the modified 
PSL. ; 


3. Lets the RET instruction complete but sets the T bit to suspend execution 
after the RET instruction (in the calling routine) on the instruction that 
follows the original call. 


STEP/RETURN is also implemented by setting a reserved bit in the saved PSL. 


Because the debugger and your program share the same address space, in some 
rare cases they can interfere with each other, causing unexpected behavior. The 
following paragraphs highlight possible sources of interference. 


Effect of Debugger on Uninitialized Variables 


Because the debugger acts as an exception handler, it uses the call stack. This 
can cause uninitialized variables saved on the call stack to be modified by the 
debugger. 


If your program references an uninitialized variable that is in this state, the 
execution of the program can be affected. 
Effect of Debugger on Memory Usage 


Another source of possible interference between the debugger and your program 
is that they share memory. If your program is sensitive to changes in memory 
usage, the execution of the program can be affected. 
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This chapter explains how to use the EXAMINE and DEPOSIT commands to 
display and modify the values of symbols declared in your program as well as the 
contents of arbitrary program locations. The chapter also explains how to use the 
EVALUATE and other commands that evaluate language expressions. 


The topics covered in this chapter are organized as follows: 


¢ General concepts related to using the EXAMINE, DEPOSIT, and EVALUATE 
commands. 


¢ Use of the commands with symbolic names—for example, the names of 
variables and routines declared in your program. Such symbolic address 
expressions are associated with compiler generated types. 


¢ Use of the commands with program locations (memory addresses or registers) 
that do not have symbolic names. Such address expressions are not 
associated with compiler generated types. 


¢ Specifying a type to override the type associated with an address expression. 


The examples in this chapter do not cover all language-dependent behavior. 
When debugging in any language, be sure to also consult the following 
documentation: 


° Appendix E, which summarizes debugger support for each language. 


¢ Section 9.3, which highlights some important differences between languages 
that you should be aware of when debugging multilanguage programs. 


¢ The documentation supplied with that language. 


4.1 General Concepts 


This section introduces the EXAMINE, DEPOSIT, and EVALUATE commands 
and discusses concepts that are common to those commands. | 


4.1.1 Accessing Variables While Debugging 


Before you try to examine or deposit into a nonstatic (stack-local or register) 
variable, its defining routine must be active—that is, on the call stack. That is, 
program execution must be suspended somewhere within the defining routine. 
See Section 3.6.2 for more information about nonstatic variables. 


You can examine a static variable at any time during program execution, and you 
can examine a nonstatic variable as soon as execution reaches its defining routine. 
However, before you examine any variable, you should step or otherwise execute 
the program beyond the point where the variable is declared and initialized. The 
value contained in any uninitialized variable should be considered invalid. 
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Many compilers optimize code to make the program run faster. If the code that 
you are debugging has been optimized, some program locations might not match 
what you would expect from looking at the source code. In particular, some 
optimization techniques eliminate certain variables, so that you no longer have 
access to them while debugging. 


‘Section 9.1 explains the effect of several optimization techniques on the 


executable code. When first debugging a program, it is best to disable 
optimization, if possible, with the /NOOPTIMIZE (or equivalent) compiler 
command qualifier. 


Note that, in some cases, when using the EXAMINE or DEPOSIT command with 
a variable name (or any other symbolic address expression) you might need to 
set a module or specify a scope or a path name. Those concepts are described in 
Chapter 5. The examples in this chapter assume that all modules are set and 
that all variable names are uniquely defined. 


4.1.2 Using the EXAMINE Command 


4-2 


For high-level language programs, the EXAMINE command is used mostly to 
display the current value of variables, and it has the following form: 


EXAMINE variable-name{, .. . ] 


Thus, for example, the following command displays the current value of the 
integer variable X: 
DBG> EXAMINE X 


MOD3\X: ie 
DBG> 


When displaying the value, the debugger prefixes the variable name with its path 
name—in this case, the name of the module where variable X is declared (see 
Section 5.3.2). 


More generally, the EXAMINE command displays the current value of the entity 
denoted by an address expression, in the type associated with that location 

(for example, integer, real, array, record, and so on). The basic format of the 
EXAMINE command is as follows: 


EXAMINE address-expressior[, .. . } 


When you enter an EXAMINE command, the debugger evaluates the address 
expression to yield a program location (a memory address or a register). The 
debugger then displays the value stored at that location as follows: 


e¢ Ifthe location has a symbolic name, the debugger formats the value according 
to the compiler generated type associated with that symbol. 


¢ Ifthe location does not have a symbolic name, the debugger formats the value 
in the type longword integer by default. 


See Section 4.1.4 for more information about the types associated with symbolic 
and nonsymbolic address expressions. 


By default, when displaying the value, the debugger identifies the address 
expression and its path name symbolically if symbol information is available. See 
Section 4.1.10 for additional information about symbolization of addresses. 
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4.1.3 Using the DEPOSIT Command 


For high-level languages, the DEPOSIT command is used mostly to assign a 
new value to a variable. The command is like an assignment statement in most 
programming languages, and it has the following form: 


DEPOSIT variable-name = value 


Thus, for example, the following DEPOSIT command assigns the value 23 to the 
integer variable X: 

DBG> EXAMINE X 

MOD3\X: 17 

DBG> DEPOSIT X = 23 

DBG> EXAMINE X 

MOD3\X: 23 

DBG> 


More generally, the DEPOSIT command evaluates a language expression and 
deposits the resulting value into a program location denoted by an address 
expression. The basic format of the DEPOSIT command is as follows: 


DEPOSIT address-expression = language-expression 
When you enter a DEPOSIT command, the debugger does the following: 
¢ It evaluates the address expression to yield a program location. 


e Ifthe program location has a symbolic name, the debugger associates the 
location with the symbol’s compiler generated type. If the location does not 
have a symbolic name, the debugger associates the location with the type 
longword integer, by default (see Section 4.1.4). 


¢ It evaluates the language expression in the syntax of the current language 
and in the current radix to yield a value. This behavior is identical to that of 
the EVALUATE command (see Section 4.1.5). 


¢ It checks that the value and type of the language expression is consistent 
with the type of the address expression. If you try to deposit a value that 
is incompatible with the type of the address expression, the debugger issues 
a diagnostic message. If the value is compatible, the debugger deposits the 
value into the location denoted by the address expression. 


Note that the debugger might do type conversion during a deposit operation if 
the language rules allow it. For example, assume X is an integer variable. In the 
following example, the real value 2.0 is converted to the integer value 2, which is 
then assigned to X: 


DBG> DEPOSIT X = 2.0 
DBG> EXAMINE X 
MOD3\X: 2 

DBG> 


In general, the debugger tries to follow the assignment rules for the current 
language. 
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4.1.4 Address Expressions and Their Associated Types 


The symbols that are declared in your program (variable names, routine names, 
and so on) are symbolic address expressions. They denote memory addresses 

or registers. Symbolic address expressions (also called symbolic names in this 
chapter) have compiler generated types, and the debugger knows the type and 
location that are associated with symbolic names. Section 4.1.10 explains how to 
obtain memory addresses and register names from symbolic names and how to 
symbolize program locations. 


Symbolic names include the following categories: 


¢ Variables. The associated program locations contain the current values 
of variables. Techniques for examining and depositing into variables are 
described in Section 4.2. 


¢ Routines, labels, and line numbers. The associated program locations 
contain VAX assembly-language instructions. Techniques for examining and 
depositing VAX instructions are described in Section 4.3. 


Program locations that do not have a symbolic name are not associated with 

a compiler generated type. To enable you to examine and deposit into such 
locations, the debugger associates them with the default type longword integer. 
This means that, if you specify a location that does not have a symbolic name, 
the EXAMINE command displays the contents of 4 bytes starting at the address 
specified and formats the displayed information as an integer value. In the 
following example, the memory address 926 is not associated with a symbolic 
name (note that the address is not symbolized when the EXAMINE command is 
executed), Therefore, the EXAMINE command displays the value at that address 
as a longword integer: 

DBG> EXAMINE 926 


926: 749404624 
DBG> 


Similarly, by default you can deposit up to 4 bytes of integer data into a program — 
location that does not have a symbolic name. And this data is formatted as a 
longword integer. For example: 


DBG> DEPOSIT 926 = 84 
DBG> EXAMINE 926 

926: 84 

DBG> 


Techniques for examining and depositing into locations that do not have a 
symbolic name are described in Section 4.5. 


The EXAMINE and DEPOSIT commands accept type qualifiers (/ASCII:n, 
/BYTE, and so on) that enable you to override the type associated with a 
program location. This is useful if you want the contents of the location to 
be interpreted and displayed in another type, or if you want to deposit some 
value of a particular type into a location that is associated with another type. 
Techniques for overriding a type are described in Section 4.5. 
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4.1.5 Evaluating Language Expressions 


A language expression consists of any combination of one or more symbols, 
literals, and operators that is evaluated to a single value in the syntax of the 
current language and in the current radix. (The current language and current 
radix are defined in Section 4.1.8 and Section 4.1.9, respectively.) Several 
debugger commands and constructs evaluate language expressions: 


¢ The EVALUATE and DEPOSIT commands, which are described in this 
section and in Section 4.1.3, respectively. 


¢ The IF, FOR, REPEAT, and WHILE commands (see Section 8.6). 


¢ WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET 
WATCH commands (see Section 3.5.3). 


Although this discussion applies to all commands and constructs that evaluate 
language expressions, it focuses on the use of the EVALUATE command. 


The EVALUATE command evaluates one or more language expressions in the 
syntax of the current language and in the current radix and displays the resulting 
values. The command has the following form: 


EVALUATE language-expressior[, .. . ] 


One use of the EVALUATE command is as a calculator, to perform arithmetic 
calculations that might be unrelated to your program. For example: 
DBG> EVALUATE (8+12)*6/4 


30 
DBG> 


The debugger uses the rules of operator precedence of the current language when 
evaluating language expressions. . 


You can also evaluate language expressions that include variables and other 
constructs. For example, the following EVALUATE command subtracts 3 from 
the current value of the integer variable X, multiplies the result by 4, and 
displays the resulting value: 

DBG> DEPOSIT X = 23 

DBG> EVALUATE (X - 3) * 4 


80 
DBG> 


However, you cannot evaluate a language expression that includes a function call. 
For example, if PRODUCT is a function that multiplies two integers, you cannot 
enter the EVALUATE PRODUCT(3,5) command. If your program assigns the 
returned value of a function to a variable, you can then examine the value of that 
variable. 


If an expression contains symbols with different compiler generated types, the 
debugger uses the type-conversion rules of the current language to evaluate 
the expression. If the types are incompatible, a diagnostic message is issued. 
Debugger support for operators and other constructs in language expressions is 
tabulated in Appendix E for each language. You can also obtain information by 
using the HELP LANGUAGE language-name command. 
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The built-in symbol %CURVAL denotes the current value—the value last 
displayed by an EVALUATE or EXAMINE command, or deposited by a DEPOSIT 
command. The backslash (\ ) also denotes the current value when used in that 
context. For example: 


DBG> EXAMINE X 


MOD3\X: 23 
DBG> EVALUATE %CURVAL 
23 


DBG> DEPOSIT Y = 47 
DBG> EVALUATE \ 

47 

DBG> 


4.1.5.1 Using Variables in Language Expressions 
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You can use variables in language expressions in much the same way that you 
use them in the source code of your program. 


Thus, the debugger generally interprets a variable used in a language expression 
as the current value of that variable, not the address of the variable. For example 
(X is an integer variable): ; 


DBG> DEPOSIT X = 12 
DBG> EXAMINE X 


Assign the value 12 to X 
Display the value of X 


MOD4\X: 12 

DBG> EVALUATE X ! Evaluate and display the value of X 
12 

DBG> EVALUATE X + 4 ! Add the value of X to 4 

16 


DBG> DEPOSIT X = X/2 


Divide the value of X by 2 and assign 
! the resulting value to X 


DBG> EXAMINE X ! Display the new value of X 
MOD4\X: 6 
DBG> 


Note that the use of a variable in a language expression as illustrated in the 
previous examples is generally limited to single-valued, noncomposite variables. 
Typically, you can specify a multivalued, composite variable (like an array 

or record) in a language expression only if the syntax indicates that you are 
referencing only a single value (a single element of the aggregate). For example, 
if ARR is the name of an array of integers, the following command is invalid: 
DBG> EVALUATE ARR 


SDEBUG-W-NOVALUE, reference does not have a value 
DBG> 


However, the following commands are valid because only a single element of the 
array is referenced: 


DBG> EVALUATE ARR (2) ! Evaluate element 2 of array ARR 
37 

DBG> DEPOSIT K = 5 + ARR(2) ! Deposit the sum of two integer 
DBG> ! values into an integer variable 


Note also that, if the current language is BLISS, the debugger interprets a 
variable in a language expression as the address of that variable. To denote the 
value stored in a variable, you must use the contents-of operator (period (.)). For 
example, when the language is set to BLISS: 
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DBG> EXAMINE Y ! Display the value of Y. 
MOD4\Y: 3 

DBG> EVALUATE Y ! Display the address of Y. 
02475B 

DBG> EVALUATE .Y ! Display the value of Y. 

3 

DBG> EVALUATE Y + 4 ! Add 4 to the address of Y and 
02475F ! display the resulting value. 
DBG> EVALUATE .Y + 4 ! Add 4 to the value of Y and display 
7 ! the resulting value. 

DBG> 


For all languages, to obtain the address of a variable, use the EVALUATE 
/ADDRESS command, as described in Section 4.1.10. The EVALUATE and 
EVALUATE/ADDRESS commands both display the address of an address 
expression when the language is set to BLISS. 


4.1.5.2 Numeric Type Conversion by the Debugger 
When evaluating language expressions involving numeric types of different 
precision, the debugger first converts lower-precision types to higher-precision 
types before performing the evaluation. In the following example, the debugger 
converts the integer 1 to the real 1.0 before doing the addition. 
DBG> EVALUATE 1.5 + 1 


Dea 
DBG> 


The basic rules are as follows. If integer and real types are mixed, the integer 
type is converted to the real type. If integer types of different sizes are mixed 
(for example, byte-integer and word-integer), the one with the smaller size is 
converted to the larger size. If real types of different sizes are mixed (for example, 
G_float and H_float), the one with the smaller size is converted to the larger size. 


In general, the debugger allows more numeric type conversion than the 
programming language. In addition, the hardware type used for a debugger 
calculation (word, longword, G_float, and so on) might differ from that chosen by 
the compiler. Because the debugger is not as strongly typed or as precise as some 
languages, the evaluation of an expression by the EVALUATE command might 
differ from the result that would be calculated by compiler generated code and 
obtained with the EXAMINE command. 


4.1.6 Address Expressions Compared to Language Expressions 


Do not confuse address expressions with language expressions. An address 
expression specifies a program location, whereas a language expression specifies 
a value. In particular, the EXAMINE command expects an address expression as 
its parameter, and the EVALUATE command expects a language expression as its 
parameter. These points are illustrated in the next examples. 


In the following example, the value 12 is deposited into the variable X. This is 
confirmed by the EXAMINE command. The EVALUATE command computes and 
displays the sum of the current value of X and the integer literal 6: 


DBG> DEPOSIT X = 12 
DBG> EXAMINE X 


MOD3\X: 12 

DBG> EVALUATE X + 6 
18 

DBG> 
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In the next example, the EXAMINE command displays the value currently stored 
at the memory location that is 6 bytes beyond the address of X. 


DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 


In this case the location is not associated with a compiler generated type. 
Therefore, the debugger interprets and displays the value stored at that location 
in the type longword integer (see Section 4.1.4). 


In the next example, the value of X + 6 (that is, 18) is deposited into the location 
that is 6 bytes beyond the address of X. This is confirmed by the last EXAMINE 
command. 


DBG> EXAMINE X 

MOD3\X: 12 

DBG> DEPOSIT X + 6 =X + 6 
DBG> EXAMINE X 

MOD3\X: 12 

DBG> EXAMINE X + 6 
MOD3\X+6: 18 

DBG> 


4.1.7 Specifying the Current, Previous, and Next Entity 


When using the EXAMINE and DEPOSIT commands, you can use three special 
built-in symbols (address expressions) to refer quickly to the current, previous, 
and next data locations (logical entities). These are the period (.), the circumflex 
(4), and the Return key. 


The period (.), when used by itself with an EXAMINE or DEPOSIT command, 
denotes the current entity—that is, the program location most recently referenced 
by an EXAMINE or DEPOSIT command. For example: 


DBG> EXAMINE X 
SIZE\X: 7 

DBG> DEPOSIT . = 12 
DBG> EXAMINE . 
SIZE\X: 12 

DBG> 


The circumflex (“) and Return key denote, respectively, the previous and next 
logical data locations relative to the last EXAMINE or DEPOSIT command (the 
logical predecessor and successor, respectively). The circumflex and Return key 
are useful for referring to consecutive indexed components of an array. The 
following example illustrates the use of these operators with an array of integers, 


ARR: 

DBG> EXAMINE ARR (5) ! Examine element 5 of array ARR 
MAIN\ARR(5): 448670 . 
DBG> EXAMINE * ! Examine the previous element (4) 
MAIN\ARR (4): 792802 

DBG> EXAMINE ! Examine the next element (5) 
MAIN\ARR(5): 448670 

DBG> EXAMINE ! Examine the next element (6) 
MAIN\ARR (6): 891236 

DBG> 


The debugger uses the type associated with the current entity to determine 
logical successors and predecessors. 
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You can also use the built-in symbols %CURLOC, 2PREVLOC, and %NEXTLOC 
to achieve the same purpose as the period, circumflex, and Return key, 
respectively. These symbols are useful in command procedures and also if 

your program uses the circumflex for other purposes. Moreover, using the Return 
key to signify the logical successor does not apply to all contexts. For example, 
you cannot press the Return key after typing the DEPOSIT command to indicate 
the next location, whereas you can always use the symbol 2 NEXTLOC for that 
purpose. 


Note that, like EXAMINE and DEPOSIT, the EVALUATE/ADDRESS command 
also resets the values of the current, previous, and next logical-entity built-in 
symbols (see Section 4.1.10). However, you cannot press the Return key after 
typing the EVALUATE/ADDRESS command to indicate the next location. See 
Appendix D for more information about debugger built-in symbols. 


The previous examples illustrate the use of the built-in symbols after referencing 
a symbolic name with the EXAMINE or DEPOSIT command. If you examine or 
deposit into a memory address, that location might or might not be. associated 
with a compiler generated type. When you reference a memory address, the 
debugger uses the following convention to determine logical predecessors and 
successors: 


e Ifthe address has a symbolic name (the name of a variable, component of 
a composite variable, routine, and so on), the debugger uses the associated 
compiler generated type. 


¢ Ifthe address does not have a symbolic name, the debugger uses the type 
longword integer by default. 


As the current entity is reset with new examine or deposit operations, the 
debugger associates each new location with a type in the manner indicated 
to determine logical successors and predecessors. This is shown in the next 
examples. 


Assume that a FORTRAN program has declared three variables, ARY, FLT, and 
BTE: 


¢ ARY is an array of three word integers (2 bytes each). 

¢ FLT is an F_floating type (4 bytes). 

¢ BTE is a byte integer (1 byte). 

Assume that storage for these variables has been allocated at consecutive 
addresses in memory, starting with 1000. For example: 


1000: ARY(1) 
1002: ARY(2) 
1004: ARY(3) 
1006: FLT 

1010: BTE 

1011: undefined 
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Then, examining successive logical data locations would give the following results: 


DBG> EXAMINE 1000 ! Examine ARY(1), associated with 1000. 
MOD3\ARY(1): 13 ! Current entity is now ARY(1). 

DBG> EXAMINE ! Examine next location, ARY(2), 
MOD3\ARY(2): 7 ! using type of ARY(1) as reference. 
DBG> EXAMINE ! Examine next location, ARY(3). 
MOD3\ARY(3): 19 ! Current entity is now ARY(3). 

DBG> EXAMINE ! Examine entity at 1006 (FLT). 
MOD3\FLT: 1.9117807E+07 ! Current entity is now FLT. 

DBG> EXAMINE ! Examine entity at 1010 (BTE). 
MOD3\BTE: 43 ! Current entity is now BTE. 

DBG> EXAMINE ! Examine entity at 1011 (undefined). 
1011: 17694732 ! Interpret data as longword integer. 
DBG> ! Location is not symbolized. 


The same principles apply when you use type qualifiers with the EXAMINE 
and DEPOSIT commands (see Section 4.5.2). The type specified by the qualifier 
determines the data boundary of an entity and, therefore, any logical successors 
and predecessors. 


4.1.8 Language Dependencies and the Current Language 


The debugger enables you to set your debugging context to any one of several 
VAX-supported languages. The setting of the current language determines 
how the debugger parses and interprets the names, numbers, operators, and 
expressions you specify in debugger commands, and how it displays data. 


By default, the current language is the language of the module containing the 
main program, and it is identified when you invoke the debugger. For example: 
$§ PASCAL/NOOPTIMIZE/DEBUG FORMS 


$ LINK/DEBUG FORMS 
$ RUN FORMS 


VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is PASCAL, module set to ‘FORMS’ 
DBG> 


When debugging modules whose code is written in other languages, you can 

use the SET LANGUAGE command to establish a new language dependent 
context. Section 9.3 highlights some important language differences. Appendix E 
summarizes debugger support for languages. See also the documentation supplied 
with a particular language. 


4.1.9 Specifying a Radix for Entering or Displaying Integer Data 
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The debugger can interpret and display integer data in any one of four radixes: 
decimal, hexadecimal, octal, and binary. The default radix is decimal for all 
languages except BLISS and MACRO, and it is hexadecimal for BLISS and 
MACRO. 


You can control the radix for the following kinds of integer data: 
¢ Data that you specify in address expressions or language expressions. 
¢ Data that is displayed by the EVALUATE and EXAMINE commands. 


You cannot control the radix for other kinds of integer data. For example, 
addresses are always displayed in hexadecimal radix in a SHOW CALLS display. 
Or, when specifying an integer n with various command qualifiers (/AFTER:n, 
/UP:n, and so on) you must use decimal radix. 
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The technique you use to control radix depends on your objective. To establish 
a new radix for all subsequent commands, use the SET RADIX command. For 
example: 


DBG> SET RADIX HEXADECIMAL 


After this command is executed, all integer data that you enter in address or 
language expressions is interpreted as being hexadecimal. Also, all integer data 
displayed by EVALUATE and EXAMINE commands is given in hexadecimal 
radix. 


The SHOW RADIX command identifies the current radix (which is either the 
default radix, or the radix last established by a SET RADIX command). For 
example: 

DBG> SHOW RADIX 

input radix: hexadecimal 


output radix: hexadecimal 
DBG> 


The SHOW RADIX command identifies both the input radix (for data entry) 
and the output radix (for data display). The SET RADIX command qualifiers 
INPUT and /OUTPUT enable you to specify different radixes for data entry and 
display. See the command dictionary for additional information about the SET 
‘RADIX command. 


Use the CANCEL RADIX command to restore the default radix. 


The examples that follow show several techniques for displaying or entering 
integer data in another radix without changing the current radix. 


To convert some integer data to another radix without changing the current 
radix, use the EVALUATE command with a radix qualifier (/BINARY, /DECIMAL, 
/HEXADECIMAL, /OCTAL). For example: 


DBG> SHOW RADIX 

input radix: decimal 
output radix: decimal 
DBG> EVALUATE 18 + 5 


23 ! 23 is decimal integer. 
DBG> EVALUATE/HEX 18 + 5 

00000017 ! 17 is hexadecimal integer. 
DBG> 


The radix qualifiers do not affect the radix for data entry. 


To display the current value of an integer variable (or the contents of a program 
location that has an integer type) in another radix, use the EXAMINE command 
with a radix qualifier. For example: 


DBG> EXAMINE X 


MOD4\X: 4398 ! 4398 is a decimal integer. 
DBG> EXAMINE/OCTAL . ! X is the current entity. 
MOD4\X: 00000010456 ! 10456 is an octal integer. 
DBG> 


To enter one or more integer literals in another radix without changing the 
current radix, use one of the radix built-in symbols 2BIN, 2DEC, %HEX, or 
%OCT. A radix built-in symbol directs the debugger to treat an integer literal 
that follows (or all numeric literals in a parenthesized expression that follows) as 
a binary, decimal, hexadecimal, or octal number, respectively. These symbols do 
not affect the radix for data display. For example: 


4-11 


Examining and Manipulating Program Data 
4.1 General Concepts 


DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 


DBG> EVAL %BIN 10 ! Evaluate the binary integer 10. 

2 ! 2 is a decimal integer. 

DBG> EVAL sHEX (10 + 10) ! Evaluate the hexadecimal integer 20. 

32 ! 32 is a decimal integer. 

DBG> EVAL %HEX 20 + 33 ! Treat 20 as hexadecimal, 33 as decimal. 
65 ! 65 is a decimal integer. 

DBG> EVAL/HEX %OCT 4672 ! Treat 4672 as octal and display in hex. 
000009BA ! 9BA is a hexadecimal number. 

DBG> EXAMINE X + %DEC 12 |! Examine the location 12 decimal bytes 
MOD3\X+12: 493847 ! beyond the address of X. 

DBG> DEPOS J = %OCT 7777777 =! Deposit an octal value. 

DBG> EXAMINE . ! Display that value in decimal radix. 
MOD3\J: 2097151 

DBG> EXAMINE/OCTAL . ! Display that value in octal radix. 
MOD3\J: 00007777777 

DBG> EXAMINE sHEX 0A34D ! Examine location A34D, hexadecimal. 


SHARESLIBRTL+4941: 344938193 ! 344938193 is a decimal integer. 
DBG> 


Note 


When specifying a hexadecimal integer that starts with a letter rather 
than a number (for example, A34D in the last example), add a leading 
"0". Otherwise, the debugger tries to interpret the integer as a symbol 
declared in your program. 


See Appendix D for more examples showing the use of the radix built-in symbols. 


4.1.10 Obtaining and Symbolizing Memory Addresses 
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Use the EVALUATE/ADDRESS command to determine the memory address 
or the register name associated with a symbolic address expression, such as a 
variable name, line number, routine name, or label. For example: 


DBG> EVALUATE/ADDRESS X ! A variable name 


— 2476 


DBG> EVALUATE/ADDRESS SWAP ! A routine name 


1536 
DBG> EVALUATE/ADDRESS %LINE 26 
1629 
DBG> 


The address is displayed in the current radix (as defined in Section 4.1.9). You 
can specify a radix qualifier to display the address in another radix. For example: 
DBG> EVALUATE/ADDRESS/HEX X 


000009AC 
DBG> 


If a variable is associated with a register instead of a memory address, the 
EVALUATE/ADDRESS command displays the name of the register, regardless of 
whether a radix qualifier is used. The following command indicates that variable 
K (a nonstatic variable) is associated with register R2: 

DBG> EVALUATE/ADDRESS K 

SR2 

DBG> 


Examining and Manipulating Program Data 
4.1 General Concepts 


Like the EXAMINE and DEPOSIT commands, EVALUATE/ADDRESS resets 

the values of the current, previous, and next logical-entity built-in symbols (see 
Section 4.1.7). Unlike the EVALUATE command, EVALUATE/ADDRESS does not 
affect the current-value built-in symbols, %CURVAL and backslash (\ ). 


The SYMBOLIZE command does the reverse of EVALUATE/ADDRESS, but 
without affecting the current, previous, or next logical-entity built-in symbols. It 
converts a memory address or a register name into its symbolic representation 
(including its path name) if such a representation is possible (Chapter 5 explains 
how to control symbolization). For example, the following command shows that 
variable K is associated with register R2: 

DBG> SYMBOLIZE %R2 

address MOD3\%R2: 


MOD3\K 
DBG> 


By default, symbolic mode is in effect (SET MODE SYMBOLIC). Therefore the 
debugger displays all addresses symbolically, if symbols are available for the 
addresses. For example, if you specify a numeric address with the EXAMINE 
command, the address is displayed in symbolic form if symbolic information is 
available: 


DBG> EVALUATE/ADDRESS X 


2476 

DBG> EXAMINE 2476 
MOD3\X: 16 

DBG> 


However, if you specify a register that is associated with a variable, the 
EXAMINE command does not convert the register name to the variable name. 
For example: 


DBG> EVALUATE/ADDRESS K 
SR2 

DBG> EXAMINE %R2 
MOD3\%R2: 78 

DBG> 


By entering the SET MODE NOSYMBOLIC command, you disable symbolic mode 
and cause the debugger to display numeric addresses rather than their symbolic 
names. When symbolization is disabled, the debugger might process commands 
somewhat faster because it does not need to convert numbers to names. The 
EXAMINE command has a /[NOJSYMBOLIC qualifier that enables you to control 
symbolization for a single EXAMINE command. For example: 


DBG> EVALUATE/ADDRESS Y 

512 

DBG> EXAMINE 512 

MOD3\Y: 28 

DBG> EXAMINE/NOSYMBOLIC 512 
512% .28 

DBG> 


Symbolic mode also affects the display of instructions. For example: 


DBG> EXAMINE/INSTRUCTION .%PC 
MOD5\$LINE 14+2: MOVAL L*MOD4\xX,R11 
DBG> EXAMINE/NOSYMBOL/INSTRUCTION .%PC 
1538: MOVAL 1L*1080,R11 

DBG> 


4-13 


Examining and Manipulating Program Data 
4.2 Examining and Depositing into Variables 


42 Examining and Depositing into Variables 


The examples in this section illustrate how to use the EXAMINE and DEPOSIT 
commands with variables. 


Languages differ in the types of variables they use, the names for these types, 
and the degree to which different types can be intermixed in expressions. The 
following generic types are discussed in this section. 


¢ Scalars (such as integer, real, character, or Boolean) 


¢ Strings 
e Arrays 
¢ Records 


¢ Pointers (access types) 


The most important consideration when examining and manipulating variables in 
high-level language programs is that the debugger recognizes the names, syntax, 
type constraints, and scoping rules of the variables in your program. Therefore, 
when specifying a variable with the EXAMINE or DEPOSIT commanc, you use 
the same syntax that is used in the source code. The debugger processes and 
displays the data accordingly. Similarly, when assigning a value to a variable, the 
debugger follows the typing rules of the language. It issues a diagnostic message 
if you try to deposit an incompatible value. The examples in this section show 
some of these invalid operations and the resulting diagnostics. 


When using the DEPOSIT command (or any other command), note the following 
behavior. If the debugger issues a diagnostic message with a severity level of I 
(informational), the command is still executed (the deposit is made in this case). 
The debugger aborts an illegal command line only when the severity level of the 
message is W (warning) or greater. 


See Appendix E and the language documentation for additional language-specific 
information. 


4.2.1 Scalar Types 
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The following examples illustrate use of the EXAMINE, DEPOSIT, and 
EVALUATE commands with some integer, real, and Boolean types. 


Examine a list of three integer variables: 


DBG> EXAMINE WIDTH, LENGTH, AREA 
SIZE\WIDTH: 4 

SIZE\LENGTH: 7 

SIZE\AREA: 28 

DBG> 


Deposit an integer expression: 


DBG> DEPOSIT WIDTH = CURRENT WIDTH + 10 
DBG> 


The debugger checks that a value to be assigned is compatible with the data type 
and dimensional constraints of the variable. The following example shows an 
attempt to deposit an out-of-bounds value (X was declared as a positive integer): 
DBG> DEPOSIT X = -14 


SDEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near DEPOSIT 
DBG> 


Examining and Manipulating Program Data 
4.2 Examining and Depositing into Variables 


If you try to mix numeric types (integer and real of varying precision) in a 
language expression, the debugger generally follows the rules of the language. 
Strongly typed languages do not allow much if any mixing. With some languages, 
you can deposit a real value into an integer variable. However, the real value is 
converted into an integer. For example: 


DBG> DEPOSIT I = 12345 
DBG> EXAMINE I 

MOD3\I: 12345 

DBG> DEPOSIT I = 123.45 
DBG> EXAMINE I 

MOD3\I: 123 

DBG> 


Note that, if numeric types are mixed in an expression, the debugger performs 
type conversion as discussed in Section 4.1.5.2. For example: 


DBG> DEPOSIT Y = 2.356 ! Y is of type D floating point. 
DBG> EXAMINE Y 7 
MOD3\Y: 2.35600000000000 
DBG> EVALUATE Y + 3 
5.35600000000000 
DBG> DEPOSIT R = 5.35E3 ! Ris of type F floating point. 
DBG> EXAMINE R ~ 
MOD3\R: 5350.000 
DBG> EVALUATE R*50 
267500.0 
DBG> DEPOSIT I = 22222 
DBG> EVALUATE R/I 
0.2407524 
DBG> 


The next example shows some operations with Boolean variables. The values 
TRUE and FALSE are assigned to the variables WILLING and ABLE, 
respectively. The EVALUATE command then obtains the logical conjunction 
of these values: 

DBG> DEPOSIT WILLING = TRUE 

DBG> DEPOSIT ABLE = FALSE 

DBG> EVALUATE WILLING AND ABLE 

False 

DBG> 


4.2.2 ASCII String Types 


When displaying an ASCII string value, the debugger encloses it within quotation 
marks (") or apostrophes ('), depending on the language syntax. 
For example: 


DBG> EXAMINE EMPLOYEE NAME 
PAYROLL\EMPLOYEE NAME: "Peter C. Lombardi" 
DBG> 


To deposit a string value (including a single character) into a string variable, you 
must enclose the value in quotation marks (") or apostrophes (’). For example: 


DBG> DEPOSIT PART NUMBER = "WG-7619.3-84" 
DBG> 


If the string has more ASCII characters (1 byte each) than can fit into the location 
denoted by the address expression, the debugger truncates the extra characters 
from the right and issues the following message: 


sDEBUG-I-ISTRTRU, string truncated at or near DEPOSIT 
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If the string has fewer characters, the debugger pads the remaining characters to 
the right of the string by inserting ASCII space characters. 


4.2.3 Array Types 
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You can examine an entire array aggregate, a single indexed element, or a slice 
(a range of elements). But you can deposit into only one element at a time. The 
following examples show typical operations with arrays. 


The following command displays the values of all the elements of the array 
variable ARRX, a one-dimensional array of integers: 


DBG> EXAMINE ARRX 


MOD3\ARRX 
(1): 42 
(24% 17 
(3): 278 
(4): 56 
(5): LES 
(6): 149 

DBG> 


The following command displays the value of element 4 of array ARRX (depending 
on the language, parentheses or brackets are used to denote indexed elements): 


DBG> EXAMINE ARRX (4) 

MOD3\ARRX(4): 56 

DBG> 

The following command displays the values of all the elements in a slice of ARRX. 
This slice consists of the range of elements from element 2 to element 5: 


DBG> EXAMINE ARRX (2:5) 


MOD3\ARRX 
(2): 17 
(3): 278 
(4): 56 
(5}3 113 
DBG> 


In general, a range of values to be examined is denoted by two values separated 
by a colon (valuel:value2). Depending on the language, two periods (..) can be 
used instead of a colon. 


You can deposit a value to only a single array element at a time (you cannot 
deposit to an array slice or an entire array aggregate with a single DEPOSIT 
command). For example, the following command deposits the value 53 into 
element 2 of ARRX: 


DBG> DEPOSIT ARRX(2) = 53 
DBG> 


The following command displays the values of all the elements of array REAL_ 
ARRAY, a two-dimensional array of real numbers (three per dimension): 


DBG> EXAMINE REAL ARRAY 
PROG2\REAL ARRAY 


(1,1): 27.01000 
(1,2): 31.00000 
(1,3): 12.48000 
(2,1): 15.08000 
(2;2)2 22.30000 
t2p5)s 18.73000 


DBG> 
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The debugger issues a diagnostic message if you try to deposit to an index value 
that is out of bounds. For example: 

DBG> DEPOSIT REAL ARRAY (1,4) = 26.13 

$DEBUG-I-SUBOUTBND, subscript 2 is out of bounds, value is 4, 


bounds are 1..3 
DBG> 


Note that, in the previous example the deposit operation was executed because 
the diagnostic message is of I level. This means that the value of some array 
element adjacent to (1,3), possibly (2,1) might have been affected by the out-of- 
bounds deposit operation. 


To deposit the same value to several components of an array, you can use a 
looping command, such as FOR or REPEAT. For example, assign the value RED 
to elements 1 to 4 of the array COLOR_ARRAY: 


DBG> FOR I = 1 TO 4 DO (DEPOSIT COLOR ARRAY(I) = RED) 
DBG> 


You can also use the built-in symbols (.) and (*) and the Return key to step 
through array elements, as explained in Section 4.1.7. 


4.2.4 Record Types 


You can examine an entire record aggregate, a single record component, or 
several components. But you can deposit into only one component at a time. The 
following examples show typical operations with records. 


The following command displays the values of all the components of the record 
variable PART: 


DBG> EXAMINE PART 


INVENTORY \PART: 
ITEM: "WE-1247" 
PRICE: 49.95 
IN STOCK: 24 

DBG> 


The following command displays the value of component IN_STOCK of record 
PART (general syntax): 
DBG> EXAMINE PART.IN STOCK 


INVENTORY\PART.IN STOCK: 24 
DBG> 


The following command displays the value of the same record component, using 
COBOL syntax (the language must be set to COBOL): 


DBG> EXAMINE IN STOCK OF PART 

INVENTORY\IN_STOCK of PART: 
IN STOCK: 24 

DBG> 


The following command displays the values of two components of record PART: 
DBG> EXAMINE PART.ITEM, PART.IN_ STOCK 


INVENTORY \PART. ITEM: "WE-1247" 
INVENTORY\PART.IN STOCK: 24 
DBG> 


The following command deposits a value into record component IN_STOCK: 


DBG> DEPOSIT PART.IN STOCK = 17 
DBG> 
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4.2.5 Pointer (Access) Types 


You can examine the entity designated (pointed to) by a pointer variable and 
deposit a value into that entity. You can also examine a pointer variable. 


For example, the following Pascal code declares a pointer variable A that 
designates a value of type real: 


TYPE 

T = “REAL; 
VAR 

Ast; 


The following command displays the value of the entity designated by the pointer 
variable A: 


DBG> EXAMINE A* 
MOD3\A*: 1.7 
DBG> 


In the following example, the value 3.9 is deposited into the entity designated by 
A: 

DBG> DEPOSIT A* = 3.9 

DBG> EXAMINE A* 


MOD3\A*: 3.9 
DBG> 


When you specify the name of a pointer variable with the EXAMINE command, 
the debugger displays the memory address of the object it designates. For 
example: 

DBG> EXAMINE/HEXADECIMAL A 


SAMPLE\A: 0000B2A4 
DBG> 


4.3 Examining and Depositing VAX Instructions 
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Note 


See Chapter 11 for additional information about VAX vector instructions. 


The debugger recognizes address expressions that are associated with VAX 
assembly language instructions. This enables you to examine and deposit 
instructions using the same basic techniques as with variables. 


When debugging at the instruction level, you might find it convenient to first 
enter the following command. It sets the default step mode to stepping by 
instruction: 


DBG> SET STEP INSTRUCTION 
DBG> 
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There are other step modes that enable you to execute the program to specific 
kinds of instructions (INSTRUCTION[(=opcode)], CALL, BRANCH, and so on). 
Also you can set breakpoints to interrupt execution on every instruction or on 
instructions of a particular class (SET BREAK/INSTRUCTIONI[(=opcode), /CALL, 
and so on). 


In addition you can use a screen-mode instruction display (see Section 7.2.4), to 
display the actual decoded instruction stream of your program. 


4.3.1 Examining VAX Instructions 


If you specify an address expression that is associated with an instruction in an 
EXAMINE command (for example, a line number), the debugger displays the first 
instruction at that location. You can then use the period (.), Return key, and 
circumflex character (“) to display the current, next, and previous instruction 
(logical entity), as described in Section 4.1.7. For example: 


DBG> EXAMINE SLINE 12 
MOD3\%LINE 12: MOVL (R11) ,B*16 (R11) 


DBG> EXAMINE 
MOD3\%LINE 12+4: MOVL S*#1,B*4(R11) ! Next instruction. 


DBG> EXAMINE 

MOD3\%LINE 12+8: TSTL B*16(R11) ! Next instruction. 
DBG> EXAMINE “* 

MOD3\%LINE 12+4: MOVL S*#1,B*4(R11) ! Previous instruction. 
DBG> 


Line numbers, routine names, and labels are symbolic address expressions that 
are associated with instructions. In addition, instructions might be stored at 
various other memory addresses and in certain registers during the execution of 
your program. 


The program counter (PC) is the register that contains the address of the next 
instruction to be executed by your program. The command EXAMINE .%PC 
displays that instruction. The period (.), when used directly in front of an 
address expression, denotes the "contents of" operator—that is, the contents of 
the location designated by the address expression. Note the following distinction: 


¢ EXAMINE %PC displays the current PC value, namely the address of the 
next instruction to be executed. 


e EXAMINE .%PC displays the contents of that address, namely the next 
instruction to be executed by the program. 


When you enter the EXAMINE .%PC command, you can control the amount of 
information displayed by using the /OPERANDS qualifier. For example: 


DBG> EXAMINE .%PC 


MOD3\%LINE 12: MOVL B*12 (R11) ,R1 

DBG> EXAMINE/OPERANDS .%PC 

MOD3\%LINE 12: MOVL B°12(R11),R1 
B*12(R11) MOD3\K (address 1196) contains 1 
Rl Rl contains 8 

DBG> EXAMINE/OPERANDS=FULL .%PC 

MOD3\S%LINE 12: MOVL B*12(R11),R1 


B*12(R11) R11 contains MOD3\N (address 1184), B*12(1184) evaluates to 
MOD3\K (address 1196), which contains 1 | 
Rl Rl contains 8 
DBG> 
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Use the /OPERANDS qualifier only when examining the current PC instruction. 
The information might not be reliable if you specify other locations. The command 
SET MODE [NOJOPERANDS enables you to control the default behavior of the 
EXAMINE .%PC command. 


As shown in the previous examples, the debugger knows whether an address 


expression is associated with an instruction. If it is, the EXAMINE command 
displays that instruction (you do not need to use the INSTRUCTION qualifier). 
You use the INSTRUCTION qualifier to display the contents of an arbitrary 
program location as a VAX instruction—that is, the command EXAMINE 
INSTRUCTION causes the debugger to interpret and format the contents of 
any program location as a VAX instruction (see Section 4.5.2). 


Note that, when you examine consecutive instructions in a MACRO program, 
the debugger might misinterpret data as instructions if storage for the data is 
allocated in the middle of a stream of instructions. 


The following example shows some MACRO code with two longwords of data 
storage allocated directly after the BRB instruction at line 7 (line numbers have 
been added to the example for clarity): 


module TEST 


1: -TITLE TEST 

2: 

3: TESTSSTART:: 

4: . WORD 0 

5% 

6: MOVL #2,R2 

a BRB LABEL 2 

8: 

9: -LONG “*X12345 
10: -LONG %X14465 
ll: 

12: LABEL 2: 

13: MOVL #5,R5 

14: 

15: END TESTSSTART 


The following EXAMINE command displays the instruction at the start of line 6: 


DBG> EXAMINE %SLINE 6 
TEST\TESTSSTART\%SLINE 6: MOVL S*#02,R2 
DBG> 


The following EXAMINE command correctly interprets and displays the logical 
successor entity as an instruction, at line 7: 


DBG> EXAMINE 
TEST\TESTSSTART\SLINE 7: BRB  TEST\TESTSSTART\LABEL 2 
DBG> 


However, the following three EXAMINE commands incorrectly interpret the three 
logical successors as instructions: 


DBG> EXAMINE 

TEST\TESTSSTART\SLINE 7+2: MULF3 S*#11.00000,S*#0.5625000,S*#0.5000000 
DBG> EXAMINE 

SDEBUG-W-ADDRESSMODE, instruction uses illegal or undefined addressing modes 
TEST\TESTSSTART\SLINE 7+6: MULD3 S*#0.5625000[R4],S*#0.5000000, @W*5505 (RO) 
DBG> EXAMINE | 

TESTSSTART+12: HALT 

DBG> 
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4.3.2 Depositing VAX Instructions 


DBG> 
DBG> 
DBG> 
1305 
DBG> 
734; 
DBG> 
DBG> 
734: 
DBG> 


When depositing a VAX instruction, use the following command format: 
DEPOSIT/INSTRUCTION address-expression = "VAX instruction" 


You must enclose the instruction in either quotation marks or apostrophes. You 
must also use the [NSTRUCTION qualifier with the DEPOSIT command, to 
indicate that the delimited string is an instruction and not an ASCII string. Or, 
if you plan to deposit several instructions, you can first enter the SET TYPE 
/OVERRIDE INSTRUCTION command (see Section 4.5.2). You then do not need 
to use the INSTRUCTION qualifier on the DEPOSIT command. 


VAX instructions occupy different numbers of bytes, depending on their operands. 
When depositing VAX instructions of arbitrary lengths into successive memory 
locations, use the logical successor operator (Return key) to establish the next 
unoccupied location where an instruction can be deposited. The following example 
illustrates the technique. 


SET TYPE/OVERRIDE/INST ! Set the default type to instruction. 
DEPOSIT 730 = "MOVB #77, Ri"! Deposit an instruction beginning at address 730. 


! Examine the current entity to verify the deposit. 


MOVB #77,R1 
EXAMINE ! Make the logical successor the new current entity. 


. = "MOVB #66, R2" ! Deposit the next instruction. 


! Display and verify the deposit. 


MOVB #66,R2 


When you replace an instruction, be sure that the new instruction, including 
operands, is the same length in bytes as the old instruction. If the new 
instruction is longer, you cannot deposit it without overwriting, and thereby 
destroying, the next instruction. If the new instruction occupies fewer bytes of 
memory than the old one, you must deposit NOP instructions (instructions that 
cause "no operation") in bytes of memory left unoccupied after the replacement. 
The debugger does not warn you if an instruction you are depositing will 
overwrite a subsequent instruction, nor does it remind you to fill in vacant 
bytes of memory with NOPs. 


The following example illustrates how to replace an instruction with an 
instruction of equal length. 


DBG> SET STEP INSTRUCTION ! Step by instruction. 

DBG> STEP 

stepped to 1584: PUSHAL (R11) 

DBG> STEP 

stepped to 1586: CALLS #1,L°2224 ! Instruction to be replaced. 
DBG> EXAMINE .%SPC 

1586: CALLS #1,L°2224 


DBG> EXAMINE ! Determine start of next 
1593: CALLS #0,L*2216 ! instruction (1593). 


DBG> DEPOSIT/INST 1586 = "CALLS #2,L°2224" 
! Deposit new instruction. 


DBG> EXAMINE . ! Verify that instruction 
1586: CALLS  #2,L%°2224 ! is deposited. 

DBG> EXAMINE ! Verify that the next 
1593: CALLS #0,L%*2216 ! instruction is unchanged. 
DBG> 
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4.4 Examining and Depositing into Registers 


Note 
See Chapter 11 for information about the VAX vector registers. 


The VAX architecture provides 16 general registers, some of which are used for 
temporary address and data storage. When referencing a register in a debugger 
command, use the following built-in symbols (the register name preceded by a 
percent sign (%)). 


Symbol Description 

%RO... MR11 General purpose registers (RO ... R11) 
%AP (%R12) Argument pointer (AP) 

%FP (%R13) Frame pointer (FP) 

%SP (%R14) Stack pointer (SP) 

%PC (%R15) Program counter (PC) 

%PSL Processor status longword (PSL) 


You can omit the percent sign (%) prefix if your program has not declared a 
symbol with the same name. 


You can examine the contents of all the registers. You can deposit values into all 
the registers except for SP. Use caution when depositing values into FP. 


The following examples show how to examine and deposit into registers. 


‘DBG> SHOW TYPE ! Show type for locations without 
type: long integer ! a compiler generated type. 
DBG> SHOW RADIX ! Identify current radix. 


input radix: decimal 
output radix: decimal 
DBG> EXAMINE %R11 
MOD3\%R11: 1024 

DBG> DEPOSIT $R11 = 444 ! Deposit new value into R1l. 

DBG> EXAMINE %Ril Check new value. 

Rll: 444 

DBG> EXAMINE %PC ! Display value in program counter. 
MOD\%PC: 1553 

DBG> EXAMINE %SP 
O\SSP: 2147278720 
DBG> 


Display value in Rll. 


om 


Display value in stack pointer. 


See Section 4.3.1 for specific information about the PC. 


4.4.1 The Processor Status Longword (PSL) 
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The PSL is a register whose value represents a number of processor state 
variables. The first 16 bits of the PSL (referred to separately as the processor 
status word, or PSW) contain unprivileged information about the current 
processor state. The values of these bits can be controlled by a user program. 
The latter 16 bits of the PSL, bits 16 to 31, contain privileged information and 
cannot be altered by a user-mode program. 
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The following example shows how to examine the contents of the PSL: 


DBG> EXAMINE %PSL 
MOD3\PSL: 
CMP TP FPD IS CURMOD PRVMOD IPL DV FUIVTNZ2VC 
n non n mode mode lv nnonnannnonna 
DBG> 


See the VAX Architecture Handbook for complete information about the PSL, 
including the values of the various bits. 


You can also display the information in the PSL in other formats. For example: 
DBG> EXAMINE/LONG/HEX %PSL 


MOD3\%PSL: 03C00010 

DBG> EXAMINE/LONG/BIN %PSL 

MOD3\%PSL: 00000011 11000000 00000000 00010000 
DBG> 


The command EXAMINE/PSL displays the value at any location in PSL format. 
This is useful for examining saved PSLs on the call stack. 


To disable all conditions in the PSL, clear bits 0 to 15 with the following 
DEPOSIT command: 
DBG> DEPOSIT/WORD PSL = 0 
DBG> EXAMINE PSL 
MOD3\PSL: 
CMP TP FPD IS CURMOD PRVMOD IPL DV FU IV TN 
0000 


VC 
0 0 0 0 USER USER 0 0 00 


Z 
0 
DBG> 


4.5 Specifying a Type When Examining and Depositing 


‘The preceding sections explain how to use the EXAMINE and DEPOSIT 
commands with program locations that have a symbolic name and, therefore, are 
associated with a compiler generated type. 


Section 4.5.1 describes how the debugger formats (types) data for program 
locations that do not have a symbolic name and explains how you can control the 
type for those locations. 


Section 4.5.2 explains how to override the type associated with any program 
location, including a location that has a symbolic name. 


4.5.1 Defining a Type for Locations Without a Symbolic Name 


Program locations that do not have a symbolic name and, therefore, are not 
associated with a compiler generated type have the type longword integer by 
default. Section 4.1.4 explains how to examine and deposit into such locations 
using the default type. 


The SET TYPE command enables you to change the default type. This is useful 
if you want to examine and display the contents of a location in another type, 
or if you want to deposit a value of some particular type into a location that is 
associated with another type. The possible type keywords are as follows: 
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ASCIC CONDITION_VALUE INSTRUCTION QUADWORD 

ASCID D_FLOAT LONGWORD TYPE=(¢type-expression) 
ASCII:n DATE_TIME OCTAWORD WORD 

ASCIW FLOAT PACKED 

ASCIZ G_FLOAT PSL 

BYTE H_FLOAT . PSW 


For example, the following commands set the type for locations without a 
symbolic name to, respectively, byte integer, G_float, and ASCII with 6 bytes of 
ASCII data. Each successive SET TYPE command resets the type: 

DBG> SET TYPE BYTE 


DBG> SET TYPE G FLOAT 
DBG> SET TYPE ASCII:6 


Note that the SET TYPE command, when used without the /OVERRIDE 
qualifier, does not affect the type for program locations that have a symbolic 
name (locations associated with a compiler generated type). 


The SHOW TYPE command identifies the current type for locations without a 
symbolic name. To restore the default type for such locations, enter the command 
SET TYPE LONGWORD. 


4.5.2 Overriding the Current Type 
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The SET TYPE/OVERRIDE command enables you to change the type associated 
with any program location, thereby overriding any compiler generated type. For 
example, after the following command is executed, an unqualified EXAMINE 
command displays the contents of only the first byte of the location specified 
and interprets the contents as byte integer data. An unqualified DEPOSIT 
command modifies only the first byte of the location specified and formats the 
data deposited as byte integer data. 


DBG> SET TYPE/OVERRIDE BYTE 
To identify the current override type, enter the SHOW TYPE/OVERRIDE 
command. To cancel the current override type and restore the normal 


interpretation of locations that have a symbolic name, enter the command 
CANCEL TYPE/OVERRIDE. 


Type qualifiers, used with the EXAMINE and DEPOSIT commands, enable you to 
override the type currently associated with a program location for the duration of 
a single EXAMINE or DEPOSIT command. The type qualifiers are as follows: 


/ASCIC /CONDITION_VALUE ANSTRUCTION /QUADWORD 


/ASCID /D_FLOAT /LONGWORD /TASK 

/ASCII:n /DATE_TIME /OCTAWORD /TYPE=(type-expression) 
/ASCIW = /FLOAT /PACKED /WORD 

/ASCIZ /G_FLOAT /PSL 

/BYTE /H_FLOAT /PSW 


These qualifiers override any previous SET TYPE or SET TYPE/OVERRIDE 
command as well as any compiler generated type. 
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When used with a type qualifier, the EXAMINE command displays the entity 
specified by the address expression in that type. For example: 


DBG> EXAMINE %LINE 15 ! Display line 15 in compiler 
MOD3\%SLINE 15 : MOVL #1,B%44(R11) ! generated type: instruction. 
DBG> EXAMINE/BYTE . ! Type is byte integer. 
MOD3\SLINE 15 : -48 

DBG> EXAMINE/WORD . ! Type is word integer. 
MOD3\%LINE 15 : 464 

DBG> EXAMINE/LONG . ! Type is longword integer. 
MOD3\SLINE 15 : 749404624 

DBG> EXAMINE/QUAD . ! Type is quadword integer. 
MOD3%SLINE 15 : +0130653502894178768 

DBG> EXAMINE/FLOAT . ! Type is F floating. 
MOD3%LINE 15 : 1.9117807E-38 i. 

DBG> EXAMINE/G FLOAT . ! Type is G floating. 
MOD3%LINE 15 : 1.509506018605227E-300 

DBG> EXAMINE/INSTRUCTION . ! Type is VAX instruction. 
MOD3\%SLINE 15 : MOVL #1,B*44 (R11) 

DBG> EXAMINE/ASCII . ! Type is ASCII string. 
MOD3\SLINE 15: ".." 

DBG> 


When used with a type qualifier, the DEPOSIT command deposits a value of that 
type into the location specified by the address expression, overriding the type 
associated with the address expression. 


The remaining sections provide examples of specifying integer, string, and 
user-declared types with type qualifiers and the SET TYPE command. 


4.5.2.1 Integer Types 
The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with integer type qualifiers (BYTE, /WORD, /LONGWORD). These 
qualifiers enable you to deposit a value of a particular integer type into an 
arbitrary program location. 


DBG> SHOW TYPE ! Show type for locations without 

type: long integer ! a compiler generated type. 

DBG> EVALU/ADDR . ! Current location is 724. 

724 

DBG> DEPO/BYTE . = 1 ! Deposit the value 1 into one byte 
! of memory at address 724. 

DBG> EXAM . ! By default, 4 bytes are examined. 

724: 1280461057 

DBG> EXAM/BYTE . ! Examine one byte only. 

724: 1 

DBG> DEPO/WORD . = 2 ! Deposit the value 2 into first two 
! bytes (word) of current entity. 

DBG> EXAM/WORD . ! Examine a word of the current entity. 

724: 2 


DBG> DEPO/LONG 724 = 999 ! Deposit the value 999 into 4 bytes 
!(a longword) beginning at address 724. 


DBG> EXAM/LONG 724 ! Examine 4 bytes (longword) 
724: 999 ! beginning at address 724. 
DBG> 
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4.5.2.2 ASCII String Type 


The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with the /ASCII:n type qualifier. 


When used with the DEPOSIT command, this qualifier enables you to deposit 
an ASCII string of length n into an arbitrary program location. In the example, 
the location has a symbolic name (I) and, therefore, is associated with a compiler 
generated integer type. The command format is as follows: 


DEPOSIT/ASCIl:n address-expression = "ASCII string of length n" 
The default value of n is 4 bytes. 


DBG> DEPOSIT I = "abcde" ! I has compiler generated integer type. 
¢DEBUG-W-INVNUMBER, invalid numeric string ’ abcde’ 

! So, cannot deposit string into I. 
DBG> DEP/ASCII:5 I = "abcde"! /ASCII qualifier overrides integer 

! type to deposit 5 bytes of 


! ASCII data. 
DBG> EXAMINE . ! Display value of I in compiler 
MOD3\I: 1146048327 ! generated integer type. 
DBG> EXAM/ASCII:5 . ! Display value of I as 5-byte 
MOD3\I: "abcde" ! ASCII string. 


DBG> 


If you want to enter several DEPOSIT/ASCII commands, you can establish an 
override ASCII type with the SET TYPE/OVERRIDE command. Subsequent 
EXAMINE and DEPOSIT commands then have the effect of specifying the /ASCII 
qualifier with these commands. For example: 


DBG> SET TYPE/OVER ASCII:5! Establish ASCII:5 as override type.) 


DBG> DEPOSIT I = "abcde" ! Can now deposit 5-byte string into I.) 
DBG> EXAMINE I ! Display value of I as 5-byte) 

MOD3\I: "abcde" ! ASCII string. 

DBG> CANCEL TYPE/OVERRIDE ! Cancel ASCII override type. 

DBG> EXAMINE I ! Display I in compiler generated type. 
MOD3\I: 1146048327 

DBG> 


4.5.2.3 User-Declared Types 
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The following examples illustrate the use of the EXAMINE and DEPOSIT 
commands with the /TYPE=(name) qualifier. The qualifier enables you to specify 
a user-declared override type when examining or depositing. 


For example, assume that a Pascal program contains the following code, which 
declares the enumeration type COLOR with the three values RED, GREEN, and 
BLUE: 


TYPE 
COLOR = (RED, GREEN, BLUE) ; 


During the debugging session, the SHOW SYMBOL/TYPE command identifies 
the type COLOR as it is known to the debugger: 


DBG> SHOW SYMBOL/TYPE COLOR 
data MOD3\COLOR 

enumeration type (COLOR, 3 elements), size: 1 byte 
DBG> 
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The next command displays the value at address 1000, which is not associated 
with a symbolic name. Therefore, the value 0 is displayed in the type longword 
integer, by default: 

DBG> EXAMINE 1000 


1000: 0 
DBG> 


The next command displays the value at address 1000 in the type COLOR. The 
preceding SHOW SYMBOL/TYPE command indicates that each enumeration 
element is stored in 1 byte. Therefore, the debugger converts the first byte of the 
longword integer value 0 at address 1000 to the equivalent enumeration value, 
RED (the first of the three enumeration values): 


DBG> EXAMINE/TYPE=(COLOR) 1000 
1000: RED 
DBG> 


The following DEPOSIT command deposits the value GREEN into address 1000 
with the override type COLOR. The EXAMINE command displays the value at 
address 1000 in the default type, longword integer: 


DBG> DEPOSIT/TYPE=(COLOR) 1000 = GREEN 
DBG> EXAMINE 1000 

1000: 1 

DBG> 


The following SET TYPE command establishes the type COLOR for locations, 
such as address 1000, that do not have a symbolic name. The EXAMINE 
command now displays the value at 1000 in the type COLOR: 

DBG> SET TYPE TYPE= (COLOR) 

DBG> EXAMINE 1000 


1000: GREEN 
DBG> 
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Program 


Symbolic debugging enables you to specify variable names, routine names, and so 
on, precisely as they appear in your source code. You do not need to use numeric 
memory addresses or registers when referring to program locations, although you 
can, if you want. - 


In addition, you can use symbols in the context that is appropriate for the 
program and its source language. The debugger supports the language 
conventions regarding data types, expressions, scope and visibility of entities, and 
So on. 


To have full access to the symbols that are associated with your program, you 
must compile and link the program using the /DEBUG command qualifier. 


Under these conditions, the way in which symbol information is passed from your 
source program to the debugger and is processed by the debugger is transparent 
to you in most cases. However, certain situations might require some action. 


For example, when you try to set a breakpoint on a routine named COUNTER, 
the debugger might display the following diagnostic message: 
DBG> SET BREAK COUNTER 


SDEBUG-E-NOSYMBOL, symbol ‘COUNTER’ is not in the symbol table 
DBG> 


You must then set the module where COUNTER is defined, as explained in 
Section 5.2. 


Or, the debugger might display the following message if the same symbol X is 
defined (declared) in more than one module, routine, or other program unit: 


DBG> EXAMINE X 
SDEBUG-E-NOUNIQUE, symbol ’X’ is not unique 
DBG> 


You must then resolve the symbol ambiguity, perhaps by specifying a path name 
for the symbol, as explained in Section 5.3. 


This chapter explains how to handle these and other situations related to 
accessing symbols in your program. 


The chapter discusses only the symbols (typically address expressions) that are 
derived from your source program, for example: 


¢ The names of entities that you have declared in your source code, such as 
variables, routines, labels, array elements, or record components. 


e The names of modules (compilation units) and shareable images that are 
linked with your program. 
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¢ Elements that the debugger uses to identify source code—for example, the 
specifications of source files, and source line numbers as they appear in a 
listing file or when the debugger displays source code. 


The following types of symbols are discussed in other chapters: 


¢ The symbols you create during a debugging session with the DEFINE 
command are covered in Section 8.4. 


e The debugger’s built-in symbols, such as the period (.) and %PC are 
tabulated in Appendix D and discussed throughout this manual in the 
appropriate context. 


Also, see Section 4.1.10 for information about how to obtain the memory 
addresses and register names associated with symbolic address expressions and 
how to symbolize program locations. 


Note 


If your program was optimized during compilation, certain variables 

in the program might be removed by the compiler. If you then try to 
reference such a variable, the debugger issues a warning (see Section 5.1 
and Section 9.1). 


Before you try to reference a nonstatic (stack-local or register) variable, 
its defining routine must be active on the call stack. That is, program 
execution must be suspended somewhere within the defining routine (see 
Section 3.6.2). 


5.1 Controlling Symbol Information When Compiling and Linking 
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To take full advantage of symbolic debugging, you must compile and link 
your program with the /DEBUG qualifier. The following example illustrates 
these steps with a simple Pascal program, INVENTORY, that consists of two 
compilation units whose source code is in two separate files, FORMS.PAS and 
INVENTORY.PAS. INVENTORY is the main program unit: 


$ PASCAL/NOOPTIMIZE/DEBUG FORMS, INVENTORY 
$ LINK/DEBUG INVENTORY, FORMS 


Note that the /NOOPTIMIZE qualifier is used with the compiler command 
(PASCAL, in this example). If the compiler optimizes code by default, it is best 
to disable this feature by specifying /NOOPTIMIZE (or the equivalent qualifier, if 
any, for your compiler). Otherwise, the resulting object code is optimized, possibly 
causing the contents of some program locations to be inconsistent with what you 
might expect from looking at the source code. (Section 9.1 describes some of the 
effects of optimization.) 


The next sections describe how symbol information is created and passed to the 
debugger when compiling and linking. 
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5.1.1 Compiling 


When you compile a source file using the (DEBUG qualifier, the compiler creates 
symbol records for the debug symbol table (DST records) and includes them in 
the object module being generated (such as the compiler output file FORMS.OBJ, 
in the previous example). 


DST records provide not only the names of symbols but also all relevant 
information about their use. For example: 


¢ Data types, ranges, constraints, and scopes associated with variables. 


¢ Parameter names and parameter types associated with functions and 
procedures. 


e Source line correlation records, which associate source lines with line numbers 
and source files. 


Most compilers allow you to vary the amount of DST information put in an object 
module by specifying different options with the /DEBUG qualifier. Table 5-1 
identifies the options for most compilers (refer to the documentation supplied 
with your compiler for complete information). 


Table 5—1 Compiler Options for DST Symbol Information 


Compiler Command Qualifier DST information in Object Module 

/DEBUG? Full 

/DEBUG=TRACEBACK? Traceback only (module names, routine names, and 
line numbers) 

/NODEBUG? None 


1 (DEBUG, /DEBUG=ALL, and /DEBUG=(SYMBOLS, TRACEBACK) are equivalent. 
2 (DEBUG=TRACEBACK and DEBUG=(NOSYMBOLS, TRACEBACK) are equivalent. 
3 /NODEBUG, /DEBUG=NONE, and /DEBUG=(NOSYMBOLS,NOTRACEBACK) are equivalent. 


The TRACEBACK option is a default for most compilers. That is, if you omit 
the /DEBUG qualifier, most compilers assume /DEBUG=TRACEBACK. The 
TRACEBACK option enables the VMS traceback condition handler to translate 
memory addresses into routine names and line numbers so that it can give a 
symbolic traceback if a run-time error has occurred. For example: 


$ RUN INVENTORY 


SPAS-F-ERRACCFIL, error in accessing file PASSOUTPUT 
SPAS-F-ERROPECRE, error opening/creating file 
SRMS-F-FNM, error in file name 

@TRACE-F-TRACEBACK, symbolic stack dump follows 


module name routine name line rel PC abs PC 
PAS$I0_BASIC _PASSCODE 00000192 00001CED 
PASSIO_ BASIC _PASSCODE 0000054D 000020A8 
PAS$IO_BASIC _PASSCODE 0000028B 00001DE6 
INVENTORY INVENTORY 59 00000020 000005Al 
$ ; 


Traceback information is also used by the debugger’s SHOW CALLS command. 
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5.1.2 Local and Global Symbols 


DST records contain information about all of the symbols that are defined in your 
program. These are either local or global symbols. 


Typically, a local symbol is a symbol that is referenced only within the module 
where it is defined; a global symbol is a symbol such as a routine name, 
procedure entry point, or a global data name, that is defined in one module but 
referenced in other modules. 


A global symbol that is defined in a shareable image and is referenced in 
another image (for example the main, executable, image of a program) is called a 
universal symbol. When creating a shareable image, you must explicitly define 
any universal symbols as such at link time. See Section 5.4 for information about 
universal symbols and shareable images. 


Generally, the compiler resolves references to local symbols, and the linker 
resolves references to global symbols. 


The distinction between local and global symbols is discussed in various parts of 
this chapter in connection with symbol lookup and with shareable images and 
universal symbols. 


5.1.3 Linking 


When you enter the LINK/DEBUG command to link object modules and produce 
an executable image, the linker performs several functions that affect debugging: 


e It builds a debug symbol table (DST) from the DST records contained in 
the object modules being linked. The DST is the primary source of symbol 
information during a debugging session. 


¢ It resolves references to global symbols and builds a global symbol table 
(GST). The GST duplicates some of the global symbol information already 
contained in the DST, but the GST is used by the debugger for symbol lookup 
under certain circumstances. 


¢ It puts the DST and GST in the executable image. 


¢ It sets flags in the executable image that cause the image activator to pass 
control to the debugger when you enter the RUN command. 


Note 


Section 5.4 explains how to link shareable images for debugging, including 
how to define universal symbols (global symbols that are defined within a 
shareable image and referenced from another image). 


Table 5-2 summarizes the level of DST and GST information passed to the 
debugger depending on the compiler or LINK command option. The compiler 
command qualifier controls the level of DST information passed to the linker. The 
LINK command qualifier controls not only how much DST and GST information 
is passed to the debugger but also how (or if) you can invoke the debugger. 
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Table 5-2 Effect of Compiler and Linker on DST and GST Symbol Information 


Compiler 
Command 
Qualifier’ 


/DEBUG 
/DEBUG=TRACE 
/NODEBUG 


/DEBUG 
/DEBUG=TRACE 


/NODEBUG 


/DEBUG 


Command to DST Data GST Data 
DST Data in LINK Command _ Invoke Passed Passed 
Object Module Qualifier? Debugger to Debugger to Debugger? 
Full /DEBUG RUN Full Full 
Traceback only /DEBUG RUN Traceback only Full 
None /DEBUG RUN None Full 
Full /TRACE* RUN/DEBUG Traceback only Full 
Traceback only /TRACE RUN/DEBUG Traceback only Full 
None /TRACE RUN/DEBUG None Full 
Full /NOTRACE Cannot 


1 See Table 5-1 for additional information. 
2 You must also specify the /SHAREABLE qualifier when creating a shareable image (see Section 5.4). 


3 GST data includes global symbol information that is resolved at link time. GST data for an executable image includes 
the names and values of global routines and global constants. GST data for a shareable image includes universal symbols 
(see Section 5.1.2 and Section 5.4). 


4 LINK/TRACEBACK and LINK/NODEBUG are equivalent. This is the default for the LINK command. 


If you specify /(NODEBUG with the compiler command and subsequently link and 
execute the image, the debugger issues the following message when it is invoked: 


SDEBUG-I-NOLOCALS, image does not contain local symbols 
The preceding message, which occurs whether you linked with the /TRACEBACK 


or /DEBUG qualifier, indicates that no DST has been created for that image. 
Therefore, you have access only to global symbols contained in the GST. 


If you do not specify /DEBUG with the LINK command, the debugger issues the 
following message when it is invoked: 

SDEBUG-I-NOGLOBALS, some or all global symbols not accessible 

The preceding message indicates that the only global symbol information 


available during the debugging session is information that is stored in the 
DST. 


These concepts are discussed in later sections. In particular, see Section 5.4 for 
additional information related to debugging shareable images. 


5.1.4 Controlling Symbol Information in Debugged Images 


Symbol records occupy space within the executable image. After you have 
debugged your program, you might want to link it again without using the 
/DEBUG qualifier, to make the executable image smaller. This creates an image 
with only traceback data in the DST and with a GST. 


The command LINK/NOTRACEBACK enables you to secure the contents of an 
image from users after it has been debugged. Use this command for images that 
are to be installed with privileges (see the Guide to VMS System Security and the 
Guide to Setting Up a VMS System). When you enter LINK/NOTRACEBACK, no 
symbolic information (including traceback data) is passed to the image. Moreover, 
the debugger cannot be invoked, either by the RUN/DEBUG command, or by a 
Ctrl/Y-DEBUG sequence while the program is running. 
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5.2 Setting and Canceling Modules 


You need to set a module if the debugger is unable to locate a symbol that you 
have specified (for example, a variable name X) and issues a message as in the 
following example: 


DBG> EXAMINE X 
$SDEBUG-E-NOSYMBOL, symbol 'X’ is not in the symbol table 
DBG> 


This section explains module setting and the conditions under which you might 
need to set or cancel a module, using the SET MODULE and CANCEL MODULE 
commands. 


Complete symbol information is passed from your program’s source code to the 
debugger when you compile and link the program using the /DEBUG command 
qualifier, as explained in Section 5.1. 


When you invoke the debugger, symbol information is contained in the DST 
and GST, within the executable image. The DST contains detailed information 
about local and global symbols. The GST duplicates some of the global symbol 
information contained in the DST. 


To facilitate symbol searches, the debugger loads symbol information from the 
DST and GST into a run-time symbol table (RST), which is structured for efficient 
symbol lookup. Unless symbol information is in the RST, the debugger does not 
recognize or properly interpret the associated symbol. 


Because the RST takes up memory, the debugger loads it dynamically, 
anticipating what symbols you might want to reference in the course of program 
execution. The loading process is called module setting, because all symbol 
information for a given module is loaded into the RST at one time. 


At debugger startup, all GST records are loaded into the RST because global 
symbols must be accessible throughout the debugging session. Also, the debugger 
sets the module that contains the main program (the routine specified by the 
image transfer address, where execution is suspended at the start of a debugging 
session). You therefore have access to all global symbols and to any local symbols 
that should be visible within the main program. 


Subsequently, whenever execution of the program is interrupted, the debugger 
sets the module that contains the routine in which execution is suspended. 

(For Ada programs, the debugger also sets any module that is related by a 
with-clause or subunit relationship, as explained in Section E.1.14.) This enables 
you to reference the symbols that should be visible at the current PC value (in 
addition to the global symbols). This default mode of operation is called "dynamic 
mode." When setting a module dynamically, the debugger issues a message such 
as the following: 


SDEBUG-I-DYNMODSET, setting module MOD4 
If you try to reference a symbol that is defined in a module that has not been set, 
the debugger warns you that the symbol is not in the RST. You must then use the 


SET MODULE command to set the module containing that symbol explicitly. For 
example: 
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DBG> EXAMINE X 

%DEBUG-E-NOSYMBOL, symbol ’X’ is not in the symbol table 
DBG> SET MODULE MOD3 

DBG> EXAMINE X 

MOD3\ROUT2\X: 26 

DBG> 


The SHOW MODULE command lists the modules of your program and identifies 
which modules are set. 


When a module is set, the debugger automatically allocates memory as needed 
by the RST. This can eventually slow down the debugger as more modules are 
set. If performance becomes a problem, you can use the CANCEL MODULE 
command to reduce the number of set modules, thereby automatically releasing 
memory. Or you can disable dynamic mode by entering the command SET MODE 
NODYNAMIC. When dynamic mode is disabled, the debugger does not set 
modules automatically. Use the SHOW MODE command to determine whether 
dynamic mode is enabled or disabled. 


See Appendix E for additional information about module setting specific to Ada 
programs. 


Section 5.4 explains how to set images and modules when debugging shareable 
images. 


5.3 Resolving Symbol Ambiguities 


Symbol ambiguities can occur when a symbol (for example, a variable name X) is 
defined in more than one routine or other program unit. 


In most cases, the debugger resolves symbol ambiguities automatically, using the 
scope and visibility rules of the currently set language and the ordering of routine 
calls on the call stack, as explained in Section 5.3.1. 


However, in some cases the debugger might respond as follows, when you specify 
a symbol that is defined multiple times: 


¢ It might not be able to determine the particular declaration of the symbol 
that you intended. For example: 
DBG> EXAMINE X 


SDEBUG-W-NOUNIQUE, symbol ‘X’ is not unique 
DBG> 


¢ It might reference the declaration that is visible in the current scope, not the 
one you want. 


To resolve such problems, you must specify a scope where the debugger should 
search for a particular declaration of the symbol. In the following example, the 
path name COUNTER\X uniquely specifies a particular declaration of X: 

DBG> EXAMINE COUNTER\X 


COUNTER\X: 14 
DBG> 


The next sections discuss scope concepts and explain how to resolve symbol 
ambiguities. 
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5.3.1 Symbol Lookup Conventions 


This section explains how the debugger searches for symbols, resolving 

most potential symbol ambiguities using the scope and visibility rules of the 
programming language and also its own rules. Section 5.3.2 and Section 5.3.3 
describe supplementary techniques that you can use when necessary. 


You can specify symbols in debugger commands by using either a path name or 
the exact symbol. 


If you use a path name, the debugger looks for the symbol in the scope denoted 
by the path name prefix (see Section 5.3.2). 


If you do not specify a path name prefix, by default, the debugger searches 
the RST as explained in the following paragraphs (you can modify this default 
behavior with the SET SCOPE command, as explained in Section 5.3.3). 


First, the debugger looks for symbols in the PC scope (also known as scope 

0), according to the scope and visibility rules of the currently set language. 
This means that, typically, the debugger first looks within the block or routine 
surrounding the current PC value (where execution is currently suspended). If 
the symbol is not found, the debugger searches the nesting program unit, then 
its nesting unit, and so on. The precise manner, which depends on the language, 
ensures that the correct declaration of a symbol that is defined multiple times is 
chosen. 


However, note that you can reference symbols throughout your program, not 
just those that are visible in the PC scope as defined by the language. This 

is necessary so you can set breakpoints in arbitrary areas, examine arbitrary 
variables, and so on. Therefore, if the symbol is not visible in the PC scope, the. 
debugger continues searching as follows. 


After the PC scope, the debugger searches the scope of the calling routine (if 
any), then its caller, and so on. Symbolically, the complete scope search list is 
denoted (0,1,2, ...,n), where 0 denotes the PC scope and n is the number of calls 
on the call stack. Within each scope (call frame), the debugger uses the visibility 
rules of the language to locate a symbol. 


This search list, based on the call stack, enables the debugger to differentiate 
symbols that are defined multiple times in a convenient, predictable way. 


If the symbol is still not found, the debugger searches the rest of the RST—that 
is, the other set modules and the global symbol table (GST). At this point the 
debugger does not attempt to resolve any symbol ambiguities. Instead, if more 
than one occurrence of the symbol is found, the debugger issues a message such 
as the following: 


SDEBUG-W-NOUNIQUE, symbol ’Y’ is not unique 
If you have used a SET SCOPE command to modify the default symbol search 


behavior, you can restore the default behavior with the CANCEL SCOPE 
command. 
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5.3.2 Using SHOW SYMBOL and Path Names to Specify Symbols Uniquely 


If the debugger indicates that a symbol reference is "not unique," use the SHOW 
SYMBOL command to obtain all possible path names for that symbol, then 
specify a path name to reference the symbol uniquely. For example: 


DBG> EXAMINE COUNT 
SDEBUG-W-NOUNIQUE, symbol ‘COUNT’ is not unique 


DBG> SHOW SYMBOL COUNT 

data MOD7\ROUT3\BLOCK1\COUNT 
data MOD4\ROUT2\COUNT 

routine MOD2\ROUT1\ROUT3\COUNT 


DBG> EXAMINE MOD4\ROUT2\COUNT 
MOD4\ROUT2\COUNT: 12 
DBG> 


The command SHOW SYMBOL COUNT lists all declarations of the symbol 
COUNT that exist in the RST. The first two declarations of COUNT are 
variables (data). The last declaration listed is a routine. Each declaration 
is shown with its path name prefix, which indicates the path (search scope) 
the debugger must follow to reach that particular declaration. For example, 
MOD4\ ROUT2\ COUNT denotes the declaration of the symbol COUNT in 
routine ROUT2 of module MOD4. 


The path name format is as follows. The leftmost element of a path name 
identifies the module containing the symbol. Moving toward the right, the path 
name lists the successively nested routines and blocks that lead to the particular 
declaration of the symbol (which is the rightmost element). 


Although the debugger always displays symbols with their path names, you need 
to use path names in debugger commands only to resolve an ambiguity. 


The debugger looks up line numbers like any other symbols you specify (by 
default, it first looks in the module where execution is suspended). A common 
use of path names is for specifying a line number in an arbitrary module. For 
example: 


DBG> SET BREAK QUEUE _MANAGER\%LINE 26 


Note that the SHOW SYMBOL command identifies global symbols twice, because 
global symbols are included both in the DST and in the GST. For example: 


DBG> SHOW SYMBOL X 


data ALPHA\X ! global X 

data ALPHA\BETA\X ! local X 

data X (global) ! same as ALPHA\X 
DBG> 


In the case of a shareable image, its global symbols are universal symbols, 
and the SHOW SYMBOL command identifies universal symbols twice (see 
Section 5.1.2 and Section 5.4). | 


§.3.2.1 Simplifying Path Names 


Path names are often long. You can simplify the process of specifying path names 
in three ways: 


e Abbreviate a path name. 
¢ Define a brief symbol for a path name. 


e Set a new search scope so you do not have to use a path name. 
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To abbreviate a path name, delete the names of nesting program units starting 
from the left, leaving enough of the path name to specify it uniquely. For 
example, ROUT3\ COUNT is a valid abbreviated path name for the routine 

in the first example of Section 5.3.2. 


To define a symbol for a path name, use the DEFINE command. For example: 


DBG> DEFINE INTX = INT STACK\CHECK\X 
DBG> EXAMINE INTX 


To set a new search scope, use the SET SCOPE command, which is described in 
Section 5.3.3. 


5.3.2.2 Specifying Symbols in Routines on the Call Stack 


You can use a numeric path name to specify the scope associated with a routine 
on the call stack (as identified in a SHOW CALLS display). The path name prefix 
"O\" denotes the PC scope, the path name prefix "1\" denotes scope 1 (the scope 
of the caller routine), and so on. 


For example, the following commands display the current values of two distinct 
declarations of Y, which are visible in scope 0 and scope 2, respectively. 


‘DBG> EXAMINE 0\Y 


DBG> EXAMINE 2\Y 
By default, the EXAMINE Y command signifies EXAMINE OVY. 


See also the description of the SET SCOPE/CURRENT command in Section 5.3.3. 
That command enables you to reset the reference for the default scope search list 
relative to the call stack. 


5.3.2.3 Specifying Global Symbols 


To specify a global symbol uniquely, use a backslash (\ ) as a prefix to the symbol. 
For example, the following command displays the value of the global symbol X: 


DBG> EXAMINE \X 


5.3.2.4 Specifying Routine Invocations 
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When a routine is called recursively, you might need to distinguish among several 
calls to the same routine, all of which generate new symbols with identical names. 


You can include an invocation number in a path name to indicate a particular 
call to a routine. The number must be a nonnegative integer and must follow the 
name of the rightmost routine in the path name. Zero denotes the most recent 
invocation; 1 denotes the previous invocation, and so on. For example, if PROG 
calls COMPUTE and COMPUTE calls itself recursively, and each call creates a 
new variable SUM, the following command displays the value of SUM for the 
most recent call to COMPUTE: 


DBG> EXAMINE PROG\COMPUTE 0\SUM 


To refer to the variable SUM that was generated in the previous call to 
COMPUTE, you would express the path name with a 1 in place of the 0. 


When you do not include an invocation number, the debugger assumes that the 
reference is to the most recent call to the routine (the default invocation number 
is 0). 


See also the description of the SET SCOPE/CURRENT command in Section 5.3.3. 
That command enables you to reset the reference for the default scope search list 
relative to the caii stack. 
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5.3.3 Using SET SCOPE to Specify a Symbol Search Scope 


By default, the debugger looks up symbols that you specify without a path name 
prefix by using the scope search list described in Section 5.3.1. 


The SET SCOPE command enables you to establish a new scope for symbol 
lookup, so that you do not have to use a path name when referencing symbols in 
that scope. 


In the following example, the SET SCOPE command establishes the path name 
MOD4\ ROUT2 as the new scope for symbol lookup. Then, references to Y 
without a path name prefix specify the declaration of Y that is visible in the new 
scope. 

DBG> EXAMINE Y 

SDEBUG-E-NOUNIQUE, symbol ‘Y’ is not unique 

DBG> SHOW SYMBOL Y 

data MOD7\ROUT3\BLOCK1\Y 

data MOD4\ROUT2\Y 


DBG> SET SCOPE MOD4\ROUT2 

DBG> EXAMINE Y 

MOD4\ROUT2\Y: 12 

DBG> 

After you have entered a SET SCOPE command, the debugger applies the path 
name you specified in the command to all references that are not individually 
qualified with path names. 


You can specify numeric path names with SET SCOPE (see Section 5.3.2.2). For 
example, the following command sets the current scope to be three calls down 
from the PC scope. 


DBG> SET SCOPE 3 


You can also define a scope search list to specify the order in which the debugger 
should search for symbols. For example, the following command causes the 
debugger to look for symbols first in the PC scope (scope 0) and then in the scope 
denoted by routine ROUT2 of module MOD4: 


DBG> SET SCOPE 0, MOD4\ROUT2 


The debugger’s default scope search list is equivalent to entering the following 
command (if it existed): 


DBG> SET SCOPE 0,1,2,3,... ,n 
Here the debugger searches successively down the call stack to find a symbol. 


You can use the SET SCOPE/CURRENT command to reset the reference for the 
default scope search list to another routine down the call stack. For example, the 
following command sets the scope search list to be 2,3,4, ... ,n: 


DBG> SET SCOPE/CURRENT 2 


To display the current scope search list for symbol lookup, use the SHOW SCOPE 
command. To restore the default scope search list (see Section 5.3.1), use the 
CANCEL SCOPE command. 
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5.4 Debugging Shareable Images 


By default, your program might be linked with several Digital-supplied shareable 
images (for example, the run-time library image MTHRTL.EXE). This section 
explains how to extend the concepts described in the previous sections when 
debugging user-defined shareable images. 


A shareable image is not intended to be directly executed. A shareable image 
must first be included as input in the linking of an executable image, and then 
the shareable image is loaded at run time when the executable image is run. You 
do not have to install a shareable image to debug it. Instead, you can debug your 
own private copy by assigning a logical name to it. 


See the VMS Linker Utility Manual for detailed information about linking 
shareable images. 


5.4.1 Compiling and Linking Shareable Images for Debugging 
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The basic steps in compiling and linking a shareable image for debugging are as 
follows (an example follows the steps): 


1. Compile the source files for the main image and for the shareable image, 
using the /DEBUG qualifier. 


2. Link the shareable image with the /SHAREABLE and /DEBUG command 
qualifiers, declaring any universal symbols for that image using the 
UNIVERSAL linker option. (A universal symbol is a global symbol that 
is defined in a shareable image and referenced in another image.) 


8. Link the shareable image against the main image, specifying the shareable 


image with the /SHAREABLE file qualifier as a linker option. Also specify 
the /DEBUG command qualifier. 


4. Define a logical name to point to the local copy of the shareable image. You 
must specify the device and directory as well as the image name. Otherwise 
the VMS image activator looks for an image of that name in the system 
default shareable image library directory, SYS$SHARE. 


5. Execute the main image to invoke the debugger. The shareable image is 
loaded at run time. 


These steps are illustrated next with a simple example. In the example, 
MAIN.FOR and SUB1.FOR are the source files for the main image (the 
executable image that you specify with the RUN command); SHR1.FOR and 
SHR2.FOR are the source files for the shareable image to be debugged. 


You compile the source files for each image as described in Section 5.1: 


-§ FORTRAN/NOOPT/DEBUG MAIN, SUB1 


$ FORTRAN/NOOPT/DEBUG SHR1,SHR2 


You then use the LINK command to create the shareable image, also specifying 
any universal symbols: 


$ LINK/SHAREABLE/DEBUG SHR1,SHR2, SYSSINPUT: /OPTIONS 
UNIVERSAL=SHR_ROUT 
$ 


In the preceding example, 


¢ The /SHAREABLE command qualifier creates the shareable image SHR1.EXE 
from the object files SHRi.OBJ and SHR2Z.OBu. 
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¢ The /OPTIONS qualifier appended to SYS$INPUT: enables you to specify the 
global symbol SHR_ROUT as a universal symbol interactively. 


e The /DEBUG qualifier builds a DST and a GST for SHR1.EXE and puts them 
in that image. The GST contains the universal symbol SHR_ROUT. 


You have now built the shareable image SHR1.EXE in your current default 
directory. Because SHR1.EXE is a shareable image, you do not execute it 
directly with the RUN command. Instead you link SHR1.EXE against the main 
(executable) image: 

$ LINK/DEBUG MAIN, SUB1, SYS$INPUT: /OPTION 

SHR1 . EXE/SHAREABLE 

$ 


In the preceding example, 


¢ The LINK command creates the executable image MAIN.EXE from 
MAIN.OBJ and SUB1.OBuJ. 


¢ The /DEBUG qualifier builds a DST and a GST for MAIN.EXE and puts them 
in that image. 


¢ The /SHAREABLE qualifier appended to SHR1.EXE specifies that SHR1.EXE 
is to be linked against MAIN.EXE as a shareable image. 


When you execute the resulting main image, MAIN.EXE, any shareable images 
linked against it are loaded at run time. However, by default the VMS image 
activator looks for shareable images in the system default shareable image 
library directory, SYS$SHARE. Therefore, you must define the logical name 
SHR1 to point to SHR1.EXE in your current default directory. Be sure to specify 
the device and directory: 


$ DEFINE SHR1 SYSSDISK: []SHR1.EXE 


You can now invoke the debugger to debug both MAIN and SHR1 by entering the 
following command: 


$ RUN MAIN 


5.4.2 Accessing Symbols in Shareable Images 


All the concepts covered in Section 5.1, Section 5.2, and Section 5.3 apply to the 
modules of a single image, namely the main (executable) image. This section 
provides additional information that is specific to debugging shareable images. 


When you link shareable images for debugging as explained in Section 5.4.1, 
the linker builds a DST and a GST for each image. The GST for a shareable 
image contains only universal symbols. To conserve memory, the debugger builds 
an RST for an image only when that image is "set," either dynamically by the 
debugger or when you enter a SET IMAGE command. 


The SHOW IMAGE command identifies all shareable images that are linked with 
your program, shows which images are set, and identifies the current image (see 
Section 5.4.2.2 for a definition of the current image). Only the main image is set 
initially when you invoke the debugger. 


The following sections explain how the debugger sets images dynamically 
during program execution and how you can access symbols in arbitrary images 
independently of execution. 


Refer also to Section 3.6.2.4 for information about setting watchpoints in installed 
writable shareable images. 
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5.4.2.1. Accessing Symbols in the PC Scope (Dynamic Mode) 


By default, dynamic mode is enabled. Therefore, whenever the debugger 
interrupts execution, the debugger sets the image and module where execution is 
suspended, if they are not already set. 


Dynamic mode gives you the following access to symbols automatically: 


¢ You can reference symbols defined in all set modules in the image where 
execution is suspended. 


¢ You can reference any universal symbols in the GST for that image. 


By setting other modules in that image with the SET MODULE command, you 
can reference any symbol defined in the image. 


After an image is set, it remains set until you cancel it with the CANCEL 
IMAGE command. If the debugger slows down as more images and modules 
are set, use the CANCEL IMAGE command. You can also enter the SET MODE 
NODYNAMIC command to disable dynamic mode. 


5.4.2.2 Accessing Symbols in Arbitrary Images 


The last image that you or the debugger sets is the current image. The current 
image is the debugging context for symbol lookup. Therefore, when using the 
following commands, you can reference only the symbols that are defined in the 
current image: 


¢ DEFINE/ADDRESS 
¢ DEFINE/VALUE 


¢ DEPOSIT 

¢ EVALUATE 
e EXAMINE 
e TYPE 


¢ (SET,CANCEL) BREAK 

¢ (SET,SSHOW,CANCEL) MODULE 
e (SET,CANCEL) TRACE 

¢ (SET,CANCEL) WATCH 

¢ SHOW SYMBOL 


However, note that the SHOW BREAK, SHOW TRACE, and SHOW WATCH 
commands identify any breakpoints, tracepoints, or watchpoints that have been 
set in all images. 


To reference a symbol in another image, use the SET IMAGE command to make 
the specified image the current image, then use the SET MODULE command to 
set the module where that symbol is defined (the SET IMAGE command does not 
set any modules). The following example illustrates these concepts. 


The sample program consists of a main image PROG1 and a shareable image 
SHR1. Assume that you have just invoked the debugger and that execution is 
suspended within the main program unit, in image PROG1. Now, suppose you 
want to set a breakpoint on routine ROUT2, which is defined in some module in 
image SHRI. 
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If you try to set a breakpoint on ROUT2, the debugger looks for ROUT2 in the 
current image, PROGI: 


DBG> SET BREAK ROUT2 
SDEBUG-E-NOSYMBOL, symbol ‘'ROUT2’ is not in symbol table 
DBG> 


The SHOW IMAGE command shows that image SHR1 needs to be set: 
DBG> SHOW IMAGE 


image name set base address end address 
*PROG1 yes 00000200 O00009FF 
SHR1 no 00001000 QOO01FFF 
total images: 2 bytes allocated: 32856 


DBG> SET IMAGE SHR1 
DBG> SHOW IMAGE 


image name set base address end address 
PROG1 yes 00000200 O00009FF 
*SHR1 yes 00001000 QOOO1FFF 
total images: 2 bytes allocated: 41948 

DBG> 


SHR1 is now set and is the current image. However, because the SET IMAGE 
command does not set any modules, you must set the module where ROUT2 is 
- defined before you can set the breakpoint: 


DBG> SET BREAK ROUT2 

SDEBUG-E-NOSYMBOL, symbol 'ROUT2’ is not in symbol table 
DBG> SET MODULE/ALL 

DBG> SET BREAK ROUT2 

DBG> GO 

break at routine ROUT2 

10: SUBROUTINE ROUT2 (A,B) 

DBG> 


Now that you have set image SHR1 and all its modules and have reached the 
breakpoint at ROUT2, you can debug using the normal method (for example, step 
through the routine, examine variables, and so on). 


After you have set an image and set modules within that image, the image and 
modules remain set even if you establish a new current image. However, you 
have access to symbols only in the current image at any one time. 


5.4.2.3 Accessing Universal Symbols in Run-Time Libraries and System Images 
The following paragraphs describe how to access a universal symbol (such as 
a routine name) in a run-time library or other shareable image for which no 
symbol-table information was generated. With this information you can, for 
example, use the CALL command to execute a run-time library or system-service 
routine as explained in Section 8.7. 


If no symbol-table information was generated for a shareable image, you cannot 
set the image with the SET IMAGE command. For example, suppose you want to 
set image LIBRTL, which is linked with program EIGHTQUEENS: 


DBG> SHOW IMAGE 


image name set base address end address 
*EIGHTQUEENS yes 00000200 OO0009FF 
DBGSSISHR no 00075000 000783FF 
DEBUG no 00022200 00074FFF 
LIBRTL no 00000A00 000199FF 
PASRTL no 00019A00 000221FF 
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total images: 5 bytes allocated: 108560 

DBG> SET IMAGE LIBRTL 

SDEBUG-I-UNASETIMG, unable to set image LIBRTL because 
it has no symbol table 


To set the image in such cases, use the SET MODULE command with the 
following command syntax: 


SET MODULE SHARE$image-name 


For example: 
DBG> SET MODULE SHARESLIBRTL 


The debugger creates dummy modules for each shareable image in your program. 
The names of these shareable "image modules" have the prefix "SHARE$". The 
command SHOW MODULE/SHARE identifies these shareable image modules, as 
well as the modules in the current image. 


Once a shareable image module has been set with the SET MODULE command, 
you can access all of its universal symbols. For example, the following command 
lists all of the universal symbols in LIBRTL: 


DBG> SHOW SYMBOL * IN SHARESLIBRTL 


routine SHARESLIBRTL\STRSAPPEND 
routine SHARESLIBRTL\STRSDIVIDE 
routine SHARESLIBRTL\STRSROUND 


routine SHARESLIBRTL\LIBSWAIT 
routine SHARESLIBRTL\LIBSGETDVI 


You can then specify these universal symbols with, for example, the CALL or SET 
BREAK command. 


Setting a shareable image module with the SET MODULE command loads the 
universal symbols for that image into the run-time symbol table so that you can 
reference these symbols from the current image. However, you cannot reference 
other (local or global) symbols in that image from the current image. That is, 
your debugging context remains set to the current image. 
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Controlling the Display of Source Code 


The term source code refers to statements in a programming language as they 
appear in a source file. Each line of source code is also called a source line. 


This chapter covers the following topics: 
¢ How the debugger obtains information about source files and source lines. 


¢ Specifying the location of a source file that has been moved to another 
directory after it was compiled. 


¢ Displaying source lines by specifying line numbers, code address expressions, 
or search strings. 


¢ Controlling the display of source code at breakpoints, tracepoints, and 
watchpoints and after a STEP command has been executed. 


¢ Using the SET MARGINS command to improve the display of source lines 
under certain circumstances. 


The techniques described in this chapter apply to screen mode as well as line 
(noscreen) mode. Any difference in behavior between line mode and screen mode 
is identified in this chapter and in the command dictionary for the commands 
discussed. (Screen mode is described fully in Chapter 7.) 


If your program has been optimized by the compiler, the code that is executing 
as you debug might not always match your source code. See Section 9.1 for 
information about that subject. 


6.1 How the Debugger Obtains Source Code Information 


When a compiler processes source files to generate object modules, it assigns 

a line number to each source line sequentially. For most languages, each 
compilation unit (module) starts with line 1. For others like Ada, each source file, 
which might represent several compilation units, starts with line 1. 


Line numbers appear in a source listing obtained with the /LIST compile- 
command qualifier. They also appear whenever the debugger displays source 
code, either in line mode or screen mode. Moreover, you can specify line numbers 
with several debugger commands (for example, TYPE and SET BREAK). 


The debugger displays source lines only if you have specified the /DEBUG 
command with both the compile command and the LINK command. Under these 
conditions, the symbol information created by the compiler and passed to the 
debug symbol table (DST) includes source-line correlation records. For a given 
module, source-line correlation records contain the full VMS file specification 

of each source file that contributes to that module. In addition, they associate 
source records (symbols, types, and so on) with source files and line numbers in 
the module. 
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The debug symbol table (DST) contains the full VMS file specification of each 
source file when it was compiled. Thus, by default, the debugger expects a source 
file to be in the same directory it was in at compile time. If a source file is moved 
to a different directory after it is compiled, the debugger does not find it and 
displays a warning such as the following when attempting to display source code 
from that file: 


SDEBUG-W-UNAOPNSRC, unable to open source file DISK: [JONES .WORK] PRG.FOR; 2 


In such cases, use the SET SOURCE command to direct the debugger to the new 
directory. The command can be applied to all source files for your program or to 
only the source files for specific modules. 


For example, after the following command line is entered, the debugger looks for 
all source files in WORK$:[JONES.PROG3]: 


DBG> SET SOURCE WORKS: [JONES .PROG3] 


You can specify a directory search list with the SET SOURCE command. 
For example, after the following command line is entered, the debugger 


looks for source files first in the current default directory ([]) and then in 
WORK$:[JONES.PROG3]: 


DBG> SET SOURCE [], WORKS: [JONES.PROG3] 


If you want to apply the SET SOURCE command only to the source files for a 
given module, use the /(MODULE=module-name qualifier and specify that module. 
For example, the following command line specifies that the source files for module 
SCREEN_IO are in the directory DISK2:[SMITH.SHARE] (the search of source 
files for other modules is not affected by this command): | 


DBG> SET SOURCE/MODULE=SCREEN IO DISK2: [SMITH. SHARE] 


In summary, the SET SOURCE/MODULE command specifies the location of 
source files for a particular module, whereas the SET SOURCE command 
specifies the location of source files for modules that were not mentioned 
explicitly in SET SOURCE/MODULE commands. 


Use the SHOW SOURCE command to display all source directory search lists 
currently in effect. The command displays the search lists for specific modules (as 
previously established by one or more SET SOURCE/MODULE commands) and 
the search list for all other modules (as previously established by a SET SOURCE 
command). For example: 


DBG> SET SOURCE [PROJA], [PROJB],USERS: [PETER.PROJC] 
DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2: [PROJD] 
DBG> SHOW SOURCE 

source directory search list for COBOLTEST: 


[] 
DISK$2: [PROJD] 
source directory search list for all other modules: 
[PROJA] 
[PROJB] 
USERS: [PETER.PROJC] 
DBG> 


If no SET SOURCE or SET SOURCE/MODULE command has been entered, the 
SHOW SOURCE command indicates that no search list is currently in effect. 
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Use the CANCEL SOURCE command to cancel the effect of a previous SET 
SOURCE command. Use the CANCEL SOURCE/MODULE command to cancel 
the effect of a previous SET SOURCE/MODULE command (specifying the same 
module name). 


When a source directory search list has been canceled, the debugger again 
expects the source files corresponding to the designated modules to be in the 
same directories they were in at compile time. 


See the description of the SET SOURCE command in the command dictionary for 
additional information about how the debugger locates source files that have been 
moved to another directory after compile time. 


Opening a source file requires the use of an I/O channel, a limited system 
resource. Like the debugger, your program might need to open files. To ensure 
that the debugger does not use all available I/O channels and thus cause the 
program to fail, by default the debugger can keep a maximum of 5 source files 
open at one time. To specify a different limit, use the SET MAX SOURCE_FILES 
command. For example, the following command line sets the limit to 7 source 


files: 
DBG> SET MAXIMUM SOURCE FILES 7 


Note that the value specified limits only the number of source files that can be 
kept open at any one time. If the debugger reaches this limit, it closes a file 
in order to open another one. Note also that setting the limit to a very small 
number can make the debugger’s use of source files inefficient. 


The SHOW MAX SOURCE_FILES command displays the number of source files 
that the debugger can keep open at one time. 


6.3 Displaying Source Code by Specifying Line Numbers 


The TYPE command enables you to display source lines by specifying compiler- 
assigned line numbers, where each line number designates a line of source 
code. 


For example, the following command displays line 160 and lines 22 to 24 of the 
module being debugged: 


DBG> TYPE 160, 22:24 
module COBOLTEST 

160: START-IT-PARA. 
module COBOLTEST 


22: 02 SC2V2 PIC S99V99 COMP VALUE 22.33. 

233.02 SC2V2N PIC S99V99 COMP VALUE -22.33. 

24: 02 CPP2 PIC PP99 COMP VALUE 0.0012. 
DBG> 


You can display all the source lines of a module by specifying a range of line 
numbers starting from 1 and ending at a number equal to or greater than the 
largest line number in the module. 


After displaying a source line, you can display the next line in that module by 
entering a TYPE command without a line number—that is, by entering a TYPE 
command and then pressing the Return key. For example: 
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DBG> TYPE 160 
module COBOLTEST 
160: START-IT-PARA. 
DBG> TYPE 
module COBOLTEST 
161: MOVE SC1 TO ESO. 
DBG> 


‘You can then display the next line and successive lines by entering the TYPE 
command repeatedly, in this way reading through your code one line at a time. 


To display source lines in an arbitrary module of your program, specify the 
module name with the line numbers. Use standard path name notation—that is, 
first specify the module name, then a backslash (\ ), and finally the line numbers 
(or the range of line numbers), without intervening spaces. For example, the 
following command displays line 16 of module TEST: 


DBG> TYPE TEST\16 


If you specify a module name with the TYPE command, the module must be set. 
Use the SHOW MODULE command to determine whether a particular module is 
set. Then use the SET MODULE command, if necessary (see Section 5.2). 


If you do not specify a module name with the TYPE command, the debugger 
displays source lines for the module in which execution is currently suspended, by 
default—that is, the module associated with the PC scope. If you have specified 
another scope with the SET SCOPE command the debugger displays source lines 
in the module associated with the specified scope. 


In screen mode, the output of a TYPE command updates the current source 
display (see Section 7.6.6). 


After displaying source lines at various locations in your program, you can 
redisplay the line at which execution is currently suspended by pressing keypad 
key 5 (KP5). 


6.4 Displaying Source Code by Specifying Code Address 


Expressions 
The EXAMINE/SOURCE command enables you to display the source line 
corresponding to a code address expression. A code address expression denotes 


the address of a machine code instruction and, therefore, must be one of the 
following: 


e A line number associated with one or more instructions 
¢ 6A label 

e A routine name 

e The memory address of an instruction 


You cannot specify a variable name with the EXAMINE/SOURCE command, 
because a variable name is associated with data, not with instructions. 


When you use the EXAMINE/SOURCE command, the debugger evaluates the 
address expression to obtain a memory address, determines which compiler- 
assigned line number corresponds to that address, and then displays the source 
line designated by the line number. 
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For example, the following command line displays the source line associated with 
the address (declaration) of routine SWAP: 

DBG> EXAMINE/SOURCE SWAP 

module MAIN 


47: procedure SWAP (X,Y: in out INTEGER) is 
DBG> 


If you specify a line number that is not associated with an instruction, the 
debugger issues a diagnostic message. For example: 

DBG> EXAMINE/SOURCE %LINE 6 

SDEBUG-I-LINEINFO, no line 6, previous line is 5, next line is 8 


SDEBUG-E-NOSYMBOL, symbol 'SLINE 6’ is not in the symbol table 
DBG> 


When using the EXAMINE/SOURCE command, with a symbolic address 
expression (a line number, label, or routine), you might need to set the module 
in which the entity is defined, unless that module is already set. Use the SHOW 


MODULE command to determine whether a particular module is set. Then use 
the SET MODULE command, if necessary (see Section 5.2). 


The command EXAMINE/SOURCE .%PC displays the source line corresponding 
to the current PC value (the line that is about to be executed). For example: 
DBG> EXAMINE/SOURCE .%PC 
module COBOLTEST 

L6es DISPLAY ESO. 
DBG> 
Note the use of the "contents-of" operator (.), which specifies the contents of 
the entity that follows the period. If you do not use the contents-of operator, 
the debugger tries to find a source line for the PC rather than for the address 
currently stored in the PC: 
DBG> EXAMINE/SOURCE %PC 
SDEBUG-W-NOSRCLIN, no source line for address 7FFFOQ5C 
DBG> 
The following example shows the use of a numeric path name (1\) to display 
the source line at the PC value one level down the call stack (at the call to the 
routine in which execution is suspended): 


DBG> EXAMINE/SOURCE .1\%PC 


In screen mode, the output of an EXAMINE/SOURCE command updates the 
current source display (see Section 7.6.6). 


The debugger uses the EXAMINE/SOURCE command in the following contexts to 
display source code at the current PC value. 


Keypad key 5 (KP5) is bound to the following debugger command sequence: 
EXAMINE/SOURCE .%SOURCE_SCOPE\%PC; EXAMINE/INST .%INST_SCOPE\%PC 


This command sequence displays the source line and the instruction at which 
execution is currently suspended in the current scope. Thus, pressing KP5 
enables you to quickly determine your debugging context. 


The predefined source display SRC is an automatically updated display that 
executes the following built-in command every time the debugger interrupts 
execution and prompts for commands (see Section 7.2.1 and Section C.3.1): 


EXAMINE/SOURCE .%SOURCE_SCOPE\%PC 
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The SEARCH command enables you to display any source lines that contain an 
occurrence of a specified string. 


The syntax of the SEARCH command is as follows: 
SEARCH[/qualifier, .. . ]] [range] [string] 


The range parameter can be a module name, a range of line numbers, or a 
combination of both. If you do not specify a module name, the debugger uses the 
current scope to find source lines, as with the TYPE command (see Section 6.3). 


By default, the SEARCH command displays the source line that contains the first 
(next) occurrence of a string in a specified range (SEARCH/NEXT). The command 
SEARCH/ALL displays all source lines that contain an occurrence of a string in a 
specified range. For example, the following command line displays the source line 
that contains the first occurrence of the string "pro" in module SCREEN_IO: 


DBG> SEARCH SCREEN IO pro 


The remaining examples use source lines from one COBOL module, in the current 
scope, to illustrate various aspects of the SEARCH command. 


The following command line displays all source lines within lines 40 to 50 that 
contain an occurrence of the string "D". . 


DBG> SEARCH/ALL 40:50 D 
module COBOLTEST 


40: 02 D2N COMP-2 VALUE -234560000000. 

41: 02 D COMP-2 VALUE 222222.33. 

42: 02 DN COMP-2 VALUE -222222.333333. 

47: 02 DRO COMP-2 VALUE 0.1. 

48: 02 DR5 COMP-2 VALUE 0.000001. 

49: 02 DR10 COMP-2 VALUE 0.00000000001. 

a0 2,02 DR15 COMP-2 VALUE 0.0000000000000001. 
DBG> 


After you have found an occurrence of a string in a particular module, you can 
enter the SEARCH command with no parameters to display the source line 
containing the next occurrence of the same string in the same module. This is 
analogous to using the TYPE command without a parameter to display the next 
source line. For example: 


DBG> SEARCH 42:50 D 
module COBOLTEST 
42: 02 DN COMP-2 VALUE -222222.333333. 
DBG> SEARCH 
module COBOLTEST 
47: 02 DRO COMP-2 VALUE 0.1. 
DBG> 


By default, the debugger searches for a string as specified and does not interpret 
the context surrounding an occurrence of the string (this is the behavior of 
SEARCH/STRING). If you want to locate occurrences of a string that is an 
identifier in your program (for example, a variable name) and exclude other 
occurrences of the string, use the /IDENTIFIER qualifier. The command 
SEARCH/IDENTIFIER displays only those occurrences of the string that are 
bounded on either side by a character that cannot be part of an identifier in the 
current language. 
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The défault qualifiers for the SEARCH command are /NEXT and /STRING. If you 
want to establish different default qualifiers, use the SET SEARCH command. 
For example, after the following command is executed, the SEARCH command 
behaves like SEARCH/IDENTIFIER: 


DBG> SET SEARCH IDENTIFIER 


Use the SHOW SEARCH command to display the default qualifiers currently in 
effect for the SEARCH command. For example: 


DBG> SHOW SEARCH 
search settings: search for next occurrence, as an identifier 
DBG> 


6.6 Controlling Source Display After Stepping and at Event Points 


By default, the debugger displays the associated source line when a breakpoint, 
tracepoint, or watchpoint is triggered and upon the completion of a STEP 
command. 


When you enter a STEP command, the debugger displays the source line at which 
execution is suspended after the step. For example: 


DBG> STEP 

stepped to MAIN\%LINE 16 
16: RANGE := 500; 

DBG> 


When a breakpoint or tracepoint is triggered, the debugger displays the source 
line at the breakpoint or tracepoint, respectively. For example: 


DBG> SET BREAK SWAP 
DBG> GO 


break at MAIN\SWAP 
47: procedure SWAP(X,Y: in out INTEGER) is 
DBG> 


When a watchpoint is triggered, the debugger displays the source line 
corresponding to the instruction that caused the watchpoint to be triggered. 


The SET STEP [NOJSOURCE command enables you to control the display of 
source code after a step and at breakpoints, tracepoints, and watchpoints. SET 
STEP SOURCE, the default, enables source display. SET STEP NOSOURCE 
suppresses source display. For example: 

DBG> SET STEP NOSOURCE 

DBG> STEP 

stepped to MAIN\%LINE 16 

DBG> SET BREAK SWAP 

DBG> GO 


break at MAIN\SWAP 
DBG> 


You can selectively override the effect of a SET STEP SOURCE command or 
a SET STEP NOSOURCE command by using the qualifiers /SOURCE and 
/NOSOURCE with the STEP, SET BREAK, SET TRACE, and SET WATCH 
commands. 
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The STEP/SOURCE command overrides the effect of the SET STEP NOSOURCE 
command, but only for the duration of that STEP command (similarly, STEP 
/NOSOURCE overrides the effect of SET STEP SOURCE for the duration of that 
STEP command). For example: 


DBG> SET STEP NOSOURCE 
DBG> STEP/SOURCE 
stepped to MAIN\SLINE 16 
16: RANGE := 500; 
DBG> 


The SET BREAK/SOURCE command overrides the effect of the SET STEP 
NOSOURCE command, but only for the breakpoint set with that SET BREAK 
command (similarly, SET BREAK/NOSOURCE overrides the effect of SET STEP 
SOURCE for the breakpoint set with that SET BREAK command). The same 
conventions apply to the SET TRACE and SET WATCH commands. For example: 
DBG> SET STEP SOURCE 


DBG> SET BREAK/NOSOURCE SWAP 
DBG> GO 


break at MAIN\SWAP 5 
DBG> 


6.7 Setting Margins for Source Display 


The SET MARGINS command enables you to specify the leftmost and rightmost 
source-line character positions at which to begin and end the display of a source 
line (respectively, the left and right margins). This is useful for controlling the 
display of source code when, for example, the code is deeply indented or long lines 
wrap at the right margin. In such cases, you can set the left margin to eliminate 
indented space in the source display, and you can decrease the right margin 
setting to truncate lines and prevent them from wrapping. 


For example, the following command line sets the left margin to column 20 and 
the right margin to column 35. 


DBG> SET MARGINS 20:35 


Subsequently, only that portion of the source code that is between columns 20 and 
35 is displayed when you enter commands that display source lines (for example, 
TYPE, SEARCH, STEP). Use the SHOW MARGINS command to identify the 
current margin settings for the display of source lines. 


Note that the SET MARGINS command affects only the display of source lines. 
It does not affect the display of other debugger output, as from an EXAMINE 
command. | 


The SET MARGINS command is useful mostly in line (noscreen) mode. In screen 
mode, the SET MARGINS command has no effect on the display of source lines 
in a source display, such as the predefined display SRC. 
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Screen mode enables you to see more information more conveniently than the 
default, line-oriented, display mode. In screen mode, you display different types 
of data in separate areas of the screen. You might, for example, display your 
source code in the top left half of the screen, the contents of the VAX registers in 
the top right half, debugger output in the middle, and diagnostic messages at the 
bottom, near your interactive input. 


To enable screen mode, press the PF3 key (or type the SET MODE SCREEN 
command). To return to line-oriented debugging, press GOLD-PF3 (or type the 
SET MODE NOSCREEN command). In screen mode, to re-create the default 
layout of various windows, press BLUE-MINUS (PF4 followed by the MINUS key 
(—)). 


Screen mode output is best displayed on VT100-, VT200-, or VT300-series 
terminals and workstations running VWS. The larger screen of workstations 

is particularly suitable to using a number of displays for different purposes. 
You can-use screen mode with VT52 terminals, but they are less suited to the 
formatted screen displays because they do not support the scrolling regions used 
in screen mode. 


This chapter covers the following topics: 
¢ Screen mode concepts and terminology used throughout the chapter 


¢ The predefined displays SRC, OUT, PROMPT, INST, and REG, which are 
automatically available when you enter screen mode 


¢ Scrolling, hiding, deleting, moving, and resizing a display 
¢ Creating a new display 

¢ Specifying a display window 

¢ The different kinds of displays and how to use them 


¢ Directing various types of debugger output to different displays by assigning 
display attributes 


¢ A sample display configuration that illustrates a possible use of screen mode 
e Saving the current state of your screen displays 


¢ Changing your terminal screen’s height and width during a debugging session 
and the effect on display windows 


Many screen mode commands are bound to keypad keys. See Appendix B for 
key definitions. Also, Appendix C contains screen mode information in summary 
reference format. 
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Note 


This chapter provides information common to programs that run in one or 
several processes. See Chapter 10 for additional information specific to 
multiprocess programs. 


7.1 Concepts and Terminology 


A display is a group of text lines. The text might be lines from a source file, 
assembly language instructions, the values contained in registers, your input to 
the debugger, various types of debugger output, or program input and output. 


You view a display through its window, which can occupy any rectangular area 
of the screen. Because a display’s window is typically smaller than the display, 
you can scroll the window up, down, right, and left across the display text to view 
any part of the display. 


Figure 7-1 is an example of screen mode that shows three displays. The name 
of each display (SRC, OUT, and PROMPT) appears at the top left corner of its 
window. It serves both as a tag on the display itself and as a name for future 

reference in commands. 


Figure 7-1 Default Screen Mode Display Configuration 


— SRC: module SQUARESSMAIN — scroll-source 
=-C a _Square all non-zero elements and store in output array 


DO 10 IT=1, N 
IF (INARR(I) .NE. 0) THEN 
OUTARR(K) = INARR(I) **2 
ENDIF 
10 CONTINUE 


-- Print the squared output values. Then stop. 
PRINT 20, K 
FORMAT (‘ Number of non-zero elements is’,I4) 
— OUT-output 
stepped to SQUARESSMAIN\SLINE 9 
: bo 10 IT=1, N 


SQUARESSMAIN\N: 9 
SQUARESSMAIN\K: 
stepped to SQUARRSSMATN\ SLINE 11 


oa ee 
G> EXAM N, K 

BpeS STEP 2’ 

DGB> 





ZK-6503-GE 


¢ Display SRC is a source code display (it is displaying FORTRAN code in the 
example shown in Figure 7-1). SRC’s current window is the upper half of 
the screen. Like other display windows, SRC’s window can be changed to 
accommodate different display layouts. The name of the module whose source 
code is displayed, SQUARES$MAIN, is to the right of the display name. 


¢ Display OUT, located in a window directly below SRC, shows the output of 
debugger commands. 
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¢ Display PROMPT, at the bottom of the screen, shows the debugger prompt 
and debugger input. 


Figure 7-1 is the default display configuration that is established when you first 
invoke screen mode. SRC, OUT, and PROMPT are three of the five predefined 

displays that the debugger provides by default when you enter screen mode (see 
Section 7.2). You can create additional displays. 


Every display has a memory buffer, whose size is independent of the window 
size and can be adjusted. Displays that hold source code or assembly language 
instructions enable you to see all of the lines of source code of the associated 
module or all of the instructions of the associated routine, regardless of the size 
of the memory buffer. This is because the necessary information is paged into 
the buffer as needed. For other displays, such as display OUT, the buffer size 
defines how much text the display can hold. If you add more text to the display, 
the oldest text lines are discarded to make room for the new text. 


Conceptually, displays are placed on the screen as on a pasteboard. The display 
that is most recently referenced in a command is put on top of the pasteboard by 
default. Therefore, depending on the window locations, the displays that you have 
referenced recently might overlay or hide other displays (as on a pasteboard). 


The debugger maintains a display list, which is the pasting order of displays. 
Several keypad key definitions use the display list to cycle through the displays 
currently on the pasteboard. 


Every display belongs to a display kind (see Section 7.6). The display kind 
determines what type of information the display can capture and display; for 
example, source code, assembly language instructions, debugger output of various 
types. The display kind also determines how the contents of the display are 
generated. 


The contents of a display are generated in two ways. Some displays are 
automatically updated. Their definition includes a command list that is executed 
whenever the debugger gains control from the program. The output of the 
command list forms the contents of those displays. Display SRC belongs to that 
category: it is automatically updated so that an arrow centered in the window 
shows the source line at which execution is currently suspended. 


Other displays, for example display OUT, derive their contents from commands 
you enter interactively. If you create a display of this general category, you 
must first select it (with the SELECT command) as the target display for one or 
more types of output before anything can be written to it. This is also known as 
assigning one or more display attributes to a display (see Section 7.7). 


The names of any attributes assigned to a display appear to the right of the 
display name, in lowercase letters. In Figure 7~1 SRC has the source and scroll 
attributes (SRC is the current source display and the current scrolling 
display), OUT has the output attribute (it is the current output display), 
and so on. Note that, although SRC is automatically updated by its own built-in 
command, it can also receive the output of certain interactive commands (such as 
EXAMINE/SOURCE) because it has the source attribute. 


The concepts introduced in this section are developed in more detail in the rest of 
this chapter. 
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7.2 Debugger Predefined Displays 


The debugger provides the following predefined displays that you can use to 
capture and display different kinds of data: 


SRC, the predefined source display 
OUT, the predefined output display 
PROMPT, the predefined prompt display 
INST, the predefined instruction display 
REG, the predefined register display 


When you enter screen mode, the debugger puts SRC in the top half of the 
screen, PROMPT in the bottom sixth, and OUT between SRC and PROMPT, as 
illustrated in Figure 7-1. Displays INST and REG are initially removed from the 
screen by default. 


If, after rearranging displays and windows, you want to re-create this default 
configuration, press the keypad-key sequence BLUE-MINUS (PF4 followed by the 
MINUS (—) key). 


The basic features of the predefined displays are described in the next sections. 
As explained in other parts of this chapter, you can change certain characteristics 
of these displays, such as buffer size or display attributes. You can also create 
additional displays similar to the predefined displays. 


7.2.1 Predefined Source Display (SRC) 
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Note 


See Chapter 6 for information about how to make source code available 
for display during a debugging session. | . 


The predefined display SRC (see Figure 7-1) is an automatically updated source 
display. 


You can use SRC to display source code in two basic ways: 


e By default, SRC automatically displays the source code for the module 
in which execution is currently suspended. This enables you to quickly 
determine your current debugging context. 


¢ In addition, because SRC has the source attribute by default, you can use 
it to display the source code for any part of your program as explained in 
Section 7.2.1.1. 


The name of the module whose source code is displayed is shown at the right 
of the display name, SRC. The numbers displayed at the left of the source code 
are the compiler-generated line numbers, as they might appear in a compiler- 
generated listing file. 


As you execute the program under debugger control, SRC is updated 
automatically whenever execution is suspended. The arrow in the leftmost 
column indicates the source line to be executed next. Specifically, execution is 
suspended at the first VAX instruction associated with that source line. Thus, 
the line indicated by the arrow corresponds to the current PC value. The PC 
(program counter) is a VAX register that contains the memory address of the next 
instruction to be executed. 
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If the debugger cannot locate source code for the routine in which execution is 
suspended (because, for example, the routine is a run-time library routine), it 
tries to display source code in the next routine down on the call stack for which 
‘source code is available. When displaying source code for such a routine, the 
debugger issues the following message: 


%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 
Displaying source in a caller of the current routine. 


Figure 7-2 illustrates this feature. The source display shows that a call to routine 
TYPE is currently active. TYPE corresponds to a FORTRAN run-time library 
procedure. No source code is available for that routine, so the debugger displays 
the source code of the calling routine. The output of a SHOW CALLS command, 
shown in the output display, identifies the routine where execution is suspended 
and the call sequence leading to that routine. 


In such cases, the arrow in the source window identifies the line to which 
execution returns after the routine call. Depending on the source language and 
coding style, this might be the line that contains the call statement or the next 
line. 


Figure 7-2 Screen Mode Source Display When Source Code Is Not Available 


— SRC: module TEST™scroll-source 

%DEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC 
Displaying source in a caller of the current routine 

3: CHARACTER* (*) ARRAYX 

4: TYPE *, ARRAYX 

5: RETURN 

6: END 


=> 


—- OUT-output 


stepped to SHARESFORRTL+810 
module name routine name 
SHARESFORRTL SHARESFORRTL 
eieSt TEST 


— PROMPT-error-program-prompt 
DBG> STEP 

DBG> SHOW CALLS 

DBG> 
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If your program was optimized during compilation, the source code displayed 

in SRC might not always represent the code that is actually executing. The 
predefined instruction display INST is useful in such cases, because it shows the 
exact VAX instructions that are executing. See Section 7.2.4. 


The built-in command that automatically updates display SRC is EXAMINE 
/SOURCE .%SOURCE_SCOPE\ %PC. The properties of this command are 
described in Section C.3.1 and Section 6.4. 
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7.2.1.1 Displaying Source Code in Arbitrary Program Locations 


You can use display SRC to display source code throughout your program, if 
source code is available for display: 


¢ You can scroll through the entire source display by pressing keypad key KP2 
(scroll down) or KP8 (scroll up) as explained in Section 7.3.1. This enables you 
to view any source line within the module in which execution is suspended. 


¢ You can display the source code for any routine that is currently on the call 
stack by using the SET SCOPE/CURRENT command (see Section 7.2.1.2). 


¢ Because SRC has the source attribute, you can display source code throughout 
your program by using the TYPE and EXAMINE/SOURCE commands: 


oe display arbitrary source lines use the TYPE command (see Section 6.3). 


— To display the source line associated with a code location (for example, 
a routine declaration), use the EXAMINE/SOURCE command (see 
Section 6.4). 


When using the TYPE or EXAMINE/SOURCE command, make sure that the 
module in which you want to view source code is set first. Use the SHOW 
MODULE command to determine whether a particular module is set. Then 
use the SET MODULE command, if necessary (see Section 5.2). 


After manipulating the contents of display SRC, you can redisplay the location at 
which execution is currently suspended (the default behavior of SRC) by pressing 
keypad key KP5. 


7.2.1.2 Displaying Source Code for a Routine on the Call Stack 


The command SET SCOPE/CURRENT enables you to display the source code 
for any routine that is currently on the call stack. For example, the following 
command updates display SRC so that it shows the source code for the caller of 
the routine in which execution is currently suspended: 


DBG> SET SCOPE/CURRENT 1 
To reset the default scope for displaying source code, enter the command CANCEL 


SCOPE. The command causes display SRC to show the source code for the routine 
at the top of the call stack, where execution is suspended. 


7.2.2 Predefined Output Display (OUT) 
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Figure 7—1 and Figure 7~2 show some typical debugger output in the predefined 
display OUT. 


Display OUT is a general purpose output display. By default, OUT has the output 
attribute and therefore displays any debugger output that is not directed to the 
source display SRC or the instruction display INST. For example, if display INST 
is not displayed or does not have the instruction attribute, any output that would 
otherwise update display INST is shown in display OUT. 


By default, OUT does not display debugger diagnostic messages (these appear 
in the PROMPT display). You can assign attributes to OUT so that it captures 
debugger input and diagnostics as well as normal output (see Section 7.7). 
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7.2.3 Predefined Prompt Display (PROMPT) 


The predefined display PROMPT is the display in which the debugger prompts 
for input. Figure 7-1 and Figure 7-2 show PROMPT in its default location, the 
bottom sixth of the screen. . 


‘By default, PROMPT has the program and error attributes, in addition to the 
prompt attribute. Therefore, by default, the debugger forces program output to 
PROMPT and prints diagnostic messages to that display. 


PROMPT has different properties and restrictions than other displays. This is to 
eliminate possible confusion when manipulating that display: 


¢ The debugger always keeps PROMPT on top of the display pasteboard so it 
cannot be hidden by another display. You cannot hide PROMPT (with the 
DISPLAY/HIDE command), or remove PROMPT from the pasteboard (with 
the DISPLAY/REMOVE command), or permanently delete PROMPT (with the 
CANCEL DISPLAY command). 


¢ PROMPT can have the scroll attribute, so that it can be made the default 
target display for the MOVE and EXPAND commands. But you cannot scroll 
PROMPT. 


¢ You can move PROMPT anywhere on the screen, expand it to fill the full 
screen height, and contract it down to two lines. But PROMPT must always 
occupy the full width of the screen. Therefore, you cannot move, expand, or 
contract PROMPT horizontally. 


The debugger alerts you if you try to move or expand a display such that it is 
hidden by PROMPT. 


7.2.4 Predefined Instruction Display (INST) 
Note - 


By default, the predefined instruction display INST is not shown on the 
screen and does not have the instruction attribute (see Section 7.2.4.1 and 
Section 7.2.4.2). 


Display INST is an automatically updated instruction display. It shows the 
decoded VAX assembly-language instruction stream of your program. This is the 
exact code that is executing, including the effects of any compiler. optimization. 
An example is shown in Figure 7-3. 


This type of display is useful when debugging code that has been optimized. In 
such cases some of the code being executed might not match the source code that 
is shown in a source display. See Section 9.1 for information about the effects of 
optimization. 


You can use INST in two basic ways: 


¢ By default, INST automatically displays the decoded instructions for the 
routine in which execution is currently suspended. This enables you to 
quickly determine your current debugging context. 
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Figure 7-3 Screen Mode Instruction Display 



















— INST: routine SQUARESSMAIN 
B*16 (R11) 

: BLEQ SQUARESSMAIN\SLINE 16 
Line 10: MOVL B*4 (R11) ,RO 

: TSTL We- -164 (R11) [RO] 

: BEQL SQUARESSMAIN\SLINE 13 
->ne 11: MOVL B*12 (R11) ,R1 

: MOVL B*4 (R11), , RO 

: : MULL3 W%*-164 (R11) [RO] ,W*-164 (R11) [RO],B*- ee) 

Line 13: AOBLEQ B*16(R11), B*4 (R11), SQUARESSMAIN\$LINE 
Line 16: PUSHAL L*525 

: MNEGL S%“#1,-(SP) 
— OUT-output 
stepped to SQUARESSMAIN\SLINE 9 

9: pO 10 I=1, N 

SQUARESSMAIN\N: ; 
SQUARESS$MAIN\K: 
stepped to SCURRRSSMa an EINE 11 
SQUARESSMAIN\TI: 1 
SQUARESSMAIN\K: 0 
— PROMPT-error-—program-prompt 
DBG> STEP 
DBG> EXAMINE I,K 
DBG> 
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¢ In addition, if INST has the instruction attribute, you can use it to display 
the decoded instructions for any part of your program as explained in 
Section 7.2.4.2. 


The name of the routine whose instructions are displayed is shown at the right of 
the display name, INST. The numbers displayed at the left of the instructions are 
the compiler-generated source line numbers. 


As you execute the program under debugger control, INST is updated 
automatically whenever execution is suspended. The arrow in the leftmost 
column points to the instruction at which execution is suspended. This is the 
instruction that will be executed next and whose address is the current PC value. 


The built-in command that automatically updates display INST is EXAMINE 
AINSTRUCTION .%INST_SCOPE\%PC. The properties of this command are 
described in Section C.3.4 and Section 4.3.1. 


7.2.4.1 Displaying the Instruction Display 
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By default, display INST is marked as removed (see Section 7.3.2) from the 
display pasteboard and is not visible. To show display INST, use one of the 
following methods: 


¢ Press keypad key KP7 to place displays SRC and INST side by side. This 
enables you to readily compare the source code and the decoded instruction 
stream. . 


e Press the keypad key sequence PF1 KP7 to place displays INST and REG 
side by side. 


e Enter the DISPLAY INST command to place INST in its default or most 
recently defined location (see Section 7.3.2). 
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7.2.4.2 Displaying Instructions in Arbitrary Program Locations 


You can use display INST to display decoded instructions throughout your 
program: 


¢ You can scroll through the entire instruction display by pressing keypad 
key KP2 (scroll down) or KP8 (scroll up) as explained in Section 7.3.1. This 
enables you to view any instruction within the routine in which execution is 
suspended. 


¢ You can display the instruction stream for any routine that is currently on the 
call stack by using the SET SCOPE/CURRENT command (see Section 7.2.4.3). 


¢ If INST has the instruction attribute, you can display the instructions 
for any code location throughout your program by using the EXAMINE 
/JINSTRUCTION command: 


1. To assign INST the instruction attribute, use the command SELECT 
INSTRUCTION INST (see Section 7.6.2 and Section 7.7). Note that the 
instruction attribute is automatically assigned to INST when you display 
it by pressing either keypad key KP7 or the key sequence PF1 KP7. 


2. To display the instructions associated with a code location (for example, 
a routine declaration), use the EXAMINE/INSTRUCTION command (see 
Section 4.3.1). 


If no display has the instruction attribute, the output of an EXAMINE 
/JINSTRUCTION command is directed at display OUT. 


After manipulating the contents of display INST, you can redisplay the location at 
which execution is currently suspended (the default behavior of INST) by pressing 
keypad key KP5. 


7.2.4.3 Displaying Instructions for a Routine on the Call Stack 
The command SET SCOPE/CURRENT enables you to display the instructions 
for any routine that is currently on the call stack. For example, the following 
command updates display INST so that it shows the instructions for the caller of 
the routine in which execution is currently suspended: 


DBG> SET SCOPE/CURRENT 1 
To reset the default scope for displaying instructions, enter the CANCEL SCOPE 


command. The command causes display INST to show the instructions for the 
routine at the top of the call stack, where execution is suspended. 


7.2.5 Predefined Register Display (REG) 


The predefined register display REG shows the current values, in hexadecimal 
format, of the VAX general registers (RO to R11, AP, FP, SP, PC), the four 
condition code bits (C, V, Z, and N) of the processor status longword (PSL), and 
as many of the top stack values as can be displayed through the window (see 
Figure 7-4). 
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Figure 7-4 Screen Mode Register Display 
















module SQUARESSMAIN—scroll-soure SSS SSS SS 
e°C -- Read the input array RO :00000000 R11:000004A0 +10:0002019B 





3 
4: OPEN (UNIT=8, FILE=' DATAF R1 :00000008 AP :7FF359CC +14:7FFEZ2ZBDC 
5: READ (8,*) N, (INARR(I), R2 :00000000 FP :7FF35980 +18:000009FF 
6: C R3 :7FF35994 SP :7FF35980 +1C:00000005 
7:.C -- Square all non-zero e R4 :00000000 PC :0000064D +20:00000600 
—> 8: K = 0 RS :00000000 PSL: C:0 2:0 +24:00000000 
9 DO 10 I=1, N R6 :7FF35649 PSL: V:0 N:0 +28:00000001 
10: IF(INARR(I) .NE. 0) THEN R7 :8012F9E9 @SP:00000000 +2C:0000000D 
11: K=K+l1 R8 :7FFECA52 +04:08000000 +30:7FF359CC 
12: OUTARR(K) = INAR RQ :7FFECC5SA +08:7FF359CC +34:00000000 
13 ENDIF R10: 7FFED7D4 +0C:7FF359B8 +38:00020073 





—~— OUT- output 
stepped to SQUARESSMAIN\SLINE 4 
stepped to SQUARESSMAIN\SLINE 5 
stepped to SQUARESSMAIN\SLINE 8 
SQUARESSMAIN\T: 2 
SQUARESSMAIN\K: 0 
SQUARESSMAIN\N: 4 








— PROMPT ~ error-program-prompt 
DBG> STEP 

DBG> EXAMINE I,K,N 

DBG> 
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The register values displayed are for the routine in which execution is currently 
suspended. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 


REG is initially marked as removed (see Section 7.3.2) from the display 

pasteboard and is not visible. You must use the DISPLAY command (or the 
keypad key sequence GOLD KP7) to show the REG display. Pressing GOLD KP7 
enables you to place REG next to display INST. 


If the register window is made larger, the debugger fills the remaining space with 


information contained in the user call stack. 


REG does not display the current values of the VAX vector registers. To display 


data contained in vector registers or vector control registers in screen mode, use a 


DO display. (See Section 7.6.1.) 


7.3 Manipulating Existing Displays 
This section explains how to perform the following functions: 
¢ Use the SELECT and SCROLL commands to scroll a display. 


¢ Use the DISPLAY command to show, hide, or remove a display; the CANCEL 
DISPLAY command to permanently delete a display; and the SHOW 
DISPLAY command to identify the displays that currently exist and their 
order in the display list. 


¢ Use the MOVE command to move a display across the screen. 
¢ Use the EXPAND command to expand or contract a display. 


Note also that Section 7.5 and Section 7.6 discuss more advanced techniques for 


ifn sat; 1 . nTa AW A amere An mh amen the 
modifying existing displays with the DISPLAY command—how to change the 


display window and the type of information displayed. 
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7.3.1 Scrolling a Display 


A display usually has more lines of text (and possibly longer lines) than can be 
seen through its window. The SCROLL command enables you to view text that is 
hidden beyond a window’s border. You can scroll through all displays except for 
the PROMPT display. 


The easiest way to scroll displays is with keypad keys, as described later in this 
section. First, use of the relevant commands is explained. 


You can specify a display explicitly with the SCROLL command. Typically, 
however, you first use the SELECT/SCROLL command to select the current 
scrolling display. This display then has the scroll attribute and is the default 
display for the SCROLL command. You then use the SCROLL command with 
no parameter to scroll that display up or down by a specified number of lines, or 
to the right or left by a specified number of columns. The direction and distance 
scrolled are specified with the command qualifiers (/(UP:n, /RIGHT:n, and so on). 


In the following example, the SELECT command selects display OUT as the 
current scrolling display (SCROLL can be omitted because it is the default 
qualifier); the SCROLL command then scrolls OUT to reveal text 18 lines down: 


DBG> SELECT OUT 
DBG> SCROLL/DOWN: 18 


Several useful SELECT and SCROLL command lines are assigned to keypad keys 
(see Appendix B for the keypad diagram): 


¢ Pressing key 3 assigns the scroll attribute to the next display in the display 
list after the current scrolling display. So, to select a display as the current 
scrolling display, press key 3 repeatedly until the word "scroll" appears on 
the top line of that display. 


¢ Press key KP8, KP2, KP6, or KP4 to scroll up, down, right, or left, 
respectively. The amount of scroll depends on which key state you use 
(DEFAULT, GOLD, or BLUE). 


7.3.2 Showing, Hiding, Removing, and Canceling a Display 


The DISPLAY command is the most versatile command for creating and 
manipulating displays. In its simplest form, the command puts an existing 
display on top of the pasteboard, where it appears through its current window. 
For example, the following command shows the display INST through its current 
window: 

DBG> DISPLAY INST 


Pressing keypad key KP9, which is bound to the DISPLAY 2NEXTDISP 
command, enables you to achieve this effect conveniently. The built-in function 
%NEXTDISP signifies the next display in the display list (Appendix D identifies 
all screen-related built-in functions). Each time you press KP9, the next display 
in the list is put on top of the pasteboard, in its current window. 


Note that, by default, the top line of display OUT (which identifies the display) 
coincides with the bottom line of display SRC. If SRC is on top of the pasteboard, 
its bottom line hides the top line of OUT (keep this in mind when using the 
DISPLAY command and associated keypad keys to put various displays on top of 
the pasteboard). 


To hide a display at the bottom of the pasteboard, use the DISPLAY/HIDE 
command. This command changes the order of that display in the display list. 


7-11 


Using Screen Mode 
7.3 Manipulating Existing Displays 


To remove a display from the pasteboard so that it is no longer seen (yet is not 
permanently deleted), use the DISPLAY/REMOVE command. To put a removed 
display back on the pasteboard, use the DISPLAY command. 


To delete a display permanently, use the CANCEL DISPLAY command. To 
re-create the display, use the DISPLAY command as described in Section 7.4. 


Note that you cannot hide, remove, or delete the PROMPT display. 


To identify the displays that currently exist, use the SHOW DISPLAY command. 
They are listed according to their order on the display list. The display that is on 
top of the pasteboard is listed last. 


See the command dictionary for information about the various options provided 
by the DISPLAY command qualifiers. Note also that the DISPLAY command 
accepts optional parameters that enable you to modify other characteristics 

of existing displays, namely the display window and the type of information 
displayed. The techniques are discussed in Section 7.5 and Section 7.6. 


7.3.3 Moving a Display Across the Screen 


Use the MOVE command to move a display across the screen. The qualifiers 
/UP:n, /DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of 
lines or columns by which to move the display. If you do not specify a display, the 
current scrolling display is moved. 


The easiest way to move a display is by using keypad keys: 
e Press key KP3 repeatedly as needed to select the current scrolling display. 
e Put the keypad in the MOVE state, then use keys KP8, KP2, KP4, or KP6 to 
move the display up, down, left, or right, respectively (see Appendix B). 
7.3.4 Expanding or Contracting a Display 


Use the EXPAND command to expand or contract a display. The qualifiers /UP:n, 
/DOWN:n, /RIGHT:n, and /LEFT:n specify the direction and the number of lines 
or columns by which to expand or contract the display (to contract a display, 
specify negative integer values with these qualifiers). If you do not specify a 
display, the current scrolling display is expanded or contracted. 


The easiest way to expand or contract a display is by using keypad keys. 
¢ Press key KP3 repeatedly as needed to select the current scrolling display. 


¢ Put the keypad in the EXPAND or CONTRACT state, then use keys KP8, 
KP2, KP4, or KP6 to expand or contract the display vertically or horizontally 
(see Appendix B). 


Note that the PROMPT display cannot be contracted (or expanded) horizontally. 
Also, it cannot be contracted vertically to less than two lines. 


7.4 Creating a New Display 


To create a new screen display, use the DISPLAY command. The basic syntax is 
as follows: 


DISPLAY display-name [AT window-specification] [display-kina| 
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The display name can be any name that is not already used to name a display 
(use the SHOW DISPLAY command to identify all existing displays). When you 
create a new display, it is placed on top of the pasteboard, on top of any existing 
displays (except for the predefined PROMPT display, which cannot be hidden). 
The display name appears at the top left corner of the display window. 


Section 7.5 explains the options for specifying windows. If you do not provide a 
window specification, the display is positioned in the upper or lower half of the 
screen, alternating between these locations as you create new displays. 


Section 7.6 explains the options for specifying display kinds. If you do not specify 
a display kind, an output display is created. 


For example, the following command creates a new output display named OUT2. 
The window associated with OUT2 is either the top or bottom half of the screen. 
DBG> DISPLAY OUT2 

The following command creates a new "DO" display named EXAM_XY that is 
located in the right third quarter (RQ3) of the screen. This display shows the 


current value of variables X and Y and is updated whenever the debugger gains 
control from the program. 


DBG> DISPLAY EXAM XY AT RQ3 DO (EXAMINE X,Y) 


See the command dictionary for information about the various options provided 
by the DISPLAY command qualifiers. 


7.5 Specifying a Display Window 
Display windows can occupy any rectangular portion of the screen. 


You can specify a display window when you create a display with the DISPLAY 
command, You can also change the window currently associated with a display 
by specifying a new window with the DISPLAY command. When specifying a 
window, you have the following options: 


¢ Specify a window in terms of lines and columns. 
¢ Use the name of a predefined window, such as H1. 


¢ Use the name of a window definition previously established with the SET 
WINDOW command. 


Each of these techniques is described in the next sections. When specifying 
windows, keep in mind that the PROMPT display always remains on top of the 
display pasteboard and, therefore, occludes any part of another display that 
shares the same region of the screen. 


Display windows, regardless of how specified, are dynamic. This means that, if 
you use a SET TERMINAL command to change the screen height or width, the 
window associated with a display expands or contracts in proportion to the new 
screen height or width. 


7.5.1 Specifying a Window in Terms of Lines and Columns 


The general form of a window specification is (start-line,line-count[,start- 
column,column-count]). For example, the following command creates the output 
display CALLS and specifies that its window be 7 lines deep starting at line 10, 
and 30 columns wide starting at column 50: 


DBG> DISPLAY CALLS AT (10,7,50,30) 
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If you do not specify start-column or column-count, the window occupies the full 
width of the screen. 


7.5.2 Predefined Windows 


The debugger provides many predefined windows. These have short symbolic 
names that you can use in the DISPLAY command instead of having to specify 
lines and columns. For example, the following command creates the output 
display ZIP and specifies that its window be RH1 (the top right half of the 
screen). 


DBG> DISPLAY ZIP AT RH1 


The SHOW WINDOW command identifies all predefined window definitions, as 
well as those you create with the SET WINDOW command. 


7.5.3 Creating a New Window Definition 


Although the predefined windows should be adequate for most situations, you 
can also create a new window definition with the SET WINDOW command. 
This command, which has the following form, associates a window name with a 
window specification: 


SET WINDOW window-name AT (start-line,line-count{, start-col,col-count]) 


After creating a window definition, you can simply use its name (like that of 

a predefined window) in a DISPLAY command. In the following example, the 
window definition MIDDLE is established. That definition is then used to display 
OUT through the window MIDDLE. 


DBG> SET WINDOW MIDDLE AT (9,4,30,20) 
DBG> DISPLAY OUT AT MIDDLE 


To identify all current window definitions, use the SHOW WINDOW command. 
To delete a window definition, use the CANCEL WINDOW command. 


7.6 Specifying the Display Kind 
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Every display has a display kind. The display kind determines the type of 
information a display contains and how that information is generated. 


Typically, you specify a display kind when you use the DISPLAY command to 
create a new display (if you do not specify a display kind, an output display is 
created). You can also use the DISPLAY command to change the display kind 
of an existing display. The keywords and associated parameters with which you 
specify a display kind are listed below. Each of these options is explained in the 
sections that follow (refer also to the displays illustrated in Section 7.2). 


DO (command-list) 
INSTRUCTION 
INSTRUCTION (command) 
OUTPUT 

REGISTER 

SOURCE 

SOURCE (command) 


The contents of a register display are generated and updated automatically 
by the debugger. The contents of other kinds of displays are generated by 
commands, and these display kinds fall into two general groups. 
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A display that belongs to one of the following display kinds has its contents 
updated automatically according to the command or command list you supply 
when defining that display: 


DO (command-list) 
INSTRUCTION (command) 
SOURCE (command) 


The command list specified is executed each time the debugger gains control from 
your program, provided the display is not marked as removed. The output of 
the commands forms the new contents of the display. If the display is marked 

as removed, the debugger does not execute the command list until you view that 
display (marking that display as unremoved). 


A display that belongs to one of the following display kinds derives its contents 
from commands that you enter interactively: 


INSTRUCTION 
OUTPUT 
SOURCE 


To direct debugger output to a specific display in this group, you must first select 
it with the SELECT command. The technique is explained in the next sections 
and, in further detail, in Section 7.7. After a display is selected for a certain type 
of output, the output from your commands forms the contents of the display. 


The default size of the memory buffer associated with any newly created display 
is 64 lines. For source and instruction displays, the size of the buffer only 
affects performance. In the case of a source display, source files are paged in as 
necessary as you scroll through the module. In the case of an instruction display, 
the instructions are decoded from the image as necessary as you scroll through 
the routine. 


For output and DO displays, the buffer size defines how many lines of text the 
display holds. If you add more text to the display, the oldest lines are discarded 
to make room for the new text. You can use the /SIZE qualifier on the DISPLAY 
command to change the buffer size. 


7.6.1 DO (Command{; ... ]) Display Kind 


A DO display is an automatically updated display. The commands in the 
command list are executed in the order listed each time the debugger gains 
control from your program. Their output forms the content of the display, erasing 
any previous content. 


For example, the following command creates the DO display CALLS at window 
Q3. Each time the debugger gains control from the program, the SHOW CALLS 
command is executed and the output is displayed in CALLS, replacing any 
previous contents. 


DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 
The following command creates a DO display named V2_DISP that shows the 
contents of elements 4 to 7 of the VAX vector register V2 (using FORTRAN array 


syntax). The display is automatically updated whenever the debugger gains 
control from the program: 


DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7)) 
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7.6.2 INSTRUCTION Display Kind 


An instruction display shows the output of an EXAMINE/INSTRUCTION 
command within the assembly-language instruction stream of a routine. Because 
the instructions displayed are decoded from the image being debugged and show 
the exact code that is executing, this kind of display is particularly useful in 
helping you debug optimized code (see Section 9.1). 


In the display, one line is devoted to each instruction. Source line numbers 
corresponding to the instructions are displayed in the left column. The instruction 
at the location being examined is centered in the display and is marked by an 
arrow in the left column. 


Before anything can be written to an instruction display, you must select it as the 
current instruction display with the SELECT/INSTRUCTION command. 


In the following example, the DISPLAY command creates the instruction display 
INST2 at RH1. The SELECTANSTRUCTION command then selects INST2 as 
the current instruction display. When the EXAMINE/INSTRUCTION X command 
is executed, window RH1 fills with the instruction stream surrounding the 
location denoted by X. The arrow points to the instruction at location X, which is 
centered in the display. 

DBG> DISPLAY INST2 AT RH1 INSTRUCTION 


DBG> SELECT/INSTRUCTION INST2 
DBG> EXAMINE/INSTRUCTION X 


Each subsequent EXAMINE/AINSTRUCTION command updates the display. 


7.6.3 INSTRUCTION (Command) Display Kind 


This is an instruction display that is automatically updated with the output 
of the command specified. That command, which must be an EXAMINE 
AINSTRUCTION command, is executed each time the debugger gains control 
from your program. 


For example, the following command creates the instruction display INSTS3 at 
window RS45. Each time the debugger gains control, the built-in command 
EXAMINE/INSTRUCTION .%INST_SCOPE\ %PC is executed, updating the 
display. 

DBG> DISPLAY INST3 AT RS45 INSTRUCT (EX/INST » sINST_SCOPE\%PC) 


This command creates a display that functions like the predefined display INST. 
The built-in EXAMINE/INSTRUCTION command displays the instruction at the 
current PC value in the current scope (see Section C.3.4). 


If an automatically updated instruction display is selected as the current 
instruction display, it is updated like a simple instruction display by an 
interactive EXAMINE/INSTRUCTION command (in addition to being updated by 
its built-in command). 


7.6.4 OUTPUT Display Kind 
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An output display shows any debugger output that is not directed to another 
display. New output is appended to the previous contents of the display. 


Before anything can be written to an output display, it must be selected as 
the current output display with the SELECT/OUTPUT command, or as the 
current error display with the SELECT/ERROR command, or as the current 
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information about using the SELECT command with output displays. 
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In the following example, the DISPLAY command creates the output display 
OUT2 at window T2 (the display kind OUTPUT could have been omitted from 
this example, because it is the default kind). The SELECT/OUTPUT command 
then selects OUT2 as the current output display. These two commands create a 
display that functions like the predefined display OUT. 


DBG> DISPLAY OUT2 AT T2 OUTPUT 
DBG> SELECT/OUTPUT OUT2 


OUT2 now collects any debugger output that is not directed to another display. 
For example: 


¢ The output of a SHOW CALLS command goes to OUT2. 


¢ Ifno instruction display has been selected as the current instruction display, 
the output of an EXAMINE/INSTRUCTION command goes to OUT2. 


e By default, debugger diagnostic messages are directed to the PROMPT 
display. They can be directed to OUT2 with the SELECT/ERROR command. 


7.6.5 REGISTER Display Kind 


A register display is an automatically updated display that shows the current 
values, in hexadecimal format, of the VAX general registers (RO to R11, AP, FP, 
SP, and PC), the four condition code bits (C,V, Z, and N) of the processor status 
longword (PSL), and as many of the top call stack values as can be displayed in 
the window (see Figure 7-4). 


The register values displayed are for the routine in which execution is currently 
suspended. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 


A register display does not display the current values of the VAX vector registers. 
To display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 7.6.1.) 


7.6.6 SOURCE Display Kind 


A source display shows the output of a TYPE or EXAMINE/SOURCE command 
within the source code of a module, if that source code is available. Source line 
numbers are displayed in the left column. The source line that is the output of 
the command is centered in the display and is marked by an arrow in the left 
column. If a range of lines is specified with the TYPE command, the lines are 
centered in the display, but no arrow is shown. 


Before anything can be written to a source display, you must select it as the 
current source display with the SELECT/SOURCE command. 


In the following example, the DISPLAY command creates the source display 
SRC2 at Q2. The SELECT/SOURCE command then selects SRC2 as the current 
source display. When the TYPE 34 command is executed, window RH1 fills with 
the source code surrounding line 34 of the module being debugged. The arrow 
points to line 34, which is centered in the display. 

DBG> DISPLAY SRC2 AT Q2 SOURCE 


DBG> SELECT/SOURCE SRC2 
DBG> TYPE 34 


Each subsequent TYPE or EXAMINE/SOURCE command updates the display. 
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7.6.7 SOURCE (Command) Display Kind 


This is a source display that is automatically updated with the output of the 
command specified. That command, which must be an EXAMINE/SOURCE or 
TYPE command, is executed each time the debugger gains control from your 
program. 


For example, the following command creates a source display SRC3 at window 
RS45. Each time the debugger gains control, the built-in command EXAMINE 
/SOURCE .%SOURCE_SCOPE\ %PC is executed, updating the display. 


DBG> DISPLAY SRC3 AT RS45 SOURCE (EX/SOURCE .%SOURCE_SCOPE\%PC) 


This command creates a display that functions like the predefined display SRC. 
The built-in EXAMINE/SOURCE command displays the source line for the 
current PC value in the current scope (see Section C.3.1). 


If an automatically updated source display is selected as the current source 
display, it is updated like a simple source display by an interactive EXAMINE 
/SOURCE or TYPE command (in addition to being updated by its built-in 
command). 


7.6.8 PROGRAM Display Kind 


The PROMPT display belongs to the special display kind "program." Note that 
PROMPT is the only display of that kind. You cannot specify that display kind in 
a DISPLAY command. 


To avoid possible confusion, the PROMPT display has several restrictions (see 
Section 7.2.3). 


7.7 Assigning Display Attributes 
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In screen mode, the output from commands you enter interactively is directed 
to various displays according to the type of output and the display attributes 
assigned to these displays. For example, debugger diagnostic messages go to the 
display that has the error attribute (the current error display). By assigning 
one or more attributes to a display, you can mix or isolate different kinds of 
information. 


The attributes have the following names: 


error 
input 
instruction 
output 
program 
prompt 
scroll 
source 


When a display is assigned an attribute, the name of that attribute appears 

in lowercase letters on the top border of its window, to the right of the display 
name. Note that the scroll attribute does not affect debugger output but is used 
to control the default display for the SCROLL, MOVE, and EXPAND commands. 
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By default, attributes are assigned to the predefined displays as follows: 
¢ SRC has the source and scroll attributes. 

¢ OUT has the output attribute. 

¢ PROMPT has the prompt, program, and error attributes. 


To assign an attribute to a display, use the SELECT command with the qualifier 
of the same name as the attribute. In the following example, the DISPLAY 
command creates the output display ZIP. The SELECT/OUTPUT command 
then selects ZIP as the current output display—the display that has the output 
attribute. After this command is executed, the word "output" disappears from 
the top border of the predefined output display OUT and appears instead on 
display ZIP, and all debugger output formerly directed to OUT is now directed to 
ZIP. 

DBG> DISPLAY ZIP OUTPUT 

DBG> SELECT/OUTPUT ZIP 


Specific attributes can be assigned only to certain display kinds. The following 
list identifies each of the SELECT command qualifiers, its effect, and the display 
kinds to which you can assign that attribute. 


SELECT 

Qualifier Description 

/ERROR Selects the specified display as the current error display. Directs 
any subsequent debugger diagnostic message to that display. It 
must be either an output display or the PROMPT display. If no 
display is specified, selects the PROMPT display as the current 
error display. 


ANPUT Selects the specified display as the current input display. Echoes 
any subsequent debugger input in that display. It must be an 
output display. If no display is specified, unselects the current 
input display: debugger input is not echoed to any display. 


/AINSTRUCTION Selects the specified display as the current instruction display. 
Directs the output of any subsequent EXAMINE/INSTRUCTION 
command to that display. It must be an instruction display. 
Keypad key sequence BLUE-COMMA selects the next instruction 
display in the display list as the current instruction display. If no 
display is specified, unselects the current instruction display: no 
display has the instruction attribute. 


/OUTPUT Selects the specified display as the current output display. Directs 
any subsequent debugger output to that display, except where a 
particular type of output is being directed to another display (such 
as diagnostic messages going to the current error display). The 
specified display must be either an output display or the PROMPT 
display. Keypad key sequence GOLD KP3 selects the next output 
display in the display list as the current output display. If no 
display is specified, selects the PROMPT display as the current 
output display. 

/PROGRAM Selects the specified display as the current program display. 

Tries to force any subsequent program input or output to that 
display. Currently, only the PROMPT display can be specified. 
If no display is specified, unselects the current program display: 
program output is no longer forced to the PROMPT display. 
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SELECT 
Qualifier Description 


/PROMPT Selects the specified display as the current prompt display, where 
the debugger prompts for input. Currently, only the PROMPT 
display can be specified. You cannot unselect the PROMPT 
display. ; 


/SCROLL Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. Key KP3 selects 
as the current scrolling display the next display in the display 
list after the current scrolling display. If no display is specified, 
unselects the current scrolling display: no display has the scroll 
attribute. 


/SOURCE Selects the specified display as the current source display. Directs 
the output of any subsequent TYPE or EXAMINE/SOURCE 
command to that display. It must be a source display. Keypad 
key sequence BLUE-KP3 selects the next source display in the 
display list as the current source display. If no display is specified, 
unselects the current source display: no display has the source 
attribute. 


Subject to the restrictions listed, a display can have several attributes. In the 
preceding example, ZIP was selected as the current output display. In the next 
example, ZIP is further selected as the current input, error, and scrolling display. 
After these commands are executed, debugger input, output, and diagnostics 

are logged in ZIP in the proper sequence as they occur, and ZIP is the current 
scrolling display. 


DBG> SELECT/INPUT/ERROR/SCROLL ZIP 


To identify the displays currently selected for each of the display attributes, use 
the SHOW SELECT command. 


If you use the SELECT command with a particular qualifier but without 
specifying a display name, the effect is typically to deassign that attribute (to 
"unselect" the display that had the attribute). The exact effect depends on the 
attribute, as described in the preceding list. 


7.8 A Sample Display Configuration 
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How to best use screen mode depends on your personal style and on what type 
of bug you are looking for. You might be satisfied to simply use the predefined 
displays. On the other hand, especially if you have access to a larger screen, 
you might want to create additional displays for various purposes. The following 
example might give you some ideas. 


Assume you are debugging in a high-level language and are interested in tracing 
the execution of your program through several routine calls. 


First set up the default screen configuration—that is, SRC in H1, OUT in 
S45, and PROMPT in S6 (the keypad key sequence BLUE-MINUS gives this 
configuration). SRC shows the source code of the module in which execution is 
suspended. 
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The next command creates a source display named SRC2 in RH1 that shows the 
PC value at scope 1 (one level down the call stack, at the call to the routine in 
which execution is suspended): 


DBG> DISPLAY SRC2 AT RH1 SOURCE (EXAMINE/SOURCE .1\%PC) 


Thus the left half of your screen shows the currently executing routine, whereas 
the right half shows the caller of that routine. 


The next command creates a DO display named CALLS at S4 that executes the 
SHOW CALLS command each time the debugger gains control from the program: 
DBG> DISPLAY CALLS AT S4 DO (SHOW CALLS) 


Because the top half of OUT is now hidden by CALLS, make OUT’s window 
smaller: 
DBG> DISPLAY OUT AT S5 


You can create a similar display configuration with instruction displays instead of 
source displays. 


7.9 Saving Displays and the Screen State 


The SAVE command enables you to make a "snapshot" of an existing display and 
save that copy as a new display. This is useful if, for example, you later want to 
refer to the current contents of an automatically updated display (such as a DO 
display). 

In the following example, the SAVE command saves the current contents of 
display CALLS into display CALLS4, which is created by the command: 

DBG> SAVE CALLS AS CALLS4 


The new display is removed from the pasteboard. So, to view its contents use the 
DISPLAY command: 

DBG> DISPLAY CALLS4 

The EXTRACT command has two uses. First, it enables you to save the contents 


of a display in a text file. For example, the following command extracts the 
contents of display CALLS, appending the resulting text to the file COB34.TXT: 


DBG> EXTRACT/APPEND CALLS COB34 

Second, the EXTRACT/SCREEN_LAYOUT command enables you to create 

a command procedure that can later be invoked during a debugging session 

to re-create the previous state of the screen. In the following example, the 
EXTRACT/SCREEN_LAYOUT command creates a command procedure with the 
default specification SYS$DISK:[ JDBGSCREEN.COM. The file contains all the 
commands needed to re-create the current state of the screen. 


DBG> EXTRACT/SCREEN LAYOUT 


DBG> @DBGSCREEN 


Note that you cannot save the PROMPT display as another display, or extract it 
into a file. 
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7.10 Changing the Screen Height and Width 
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During a debugging session, you might want to change the height or width of 
your terminal screen. One reason might be to accommodate long lines that would 
wrap if displayed across 80 columns. Or, if you are using a workstation, you 
might want to reformat your debugger window relative to other windows. 


To change the screen height or width, use the SET TERMINAL command. 
The general effect of the command is the same whether you are at a VT-series 
terminal or at a workstation. 


In this example, assume you are using a workstation in its default emulated 
VT100-screen mode, with a screen size of 24 lines by 80 columns. You have 
invoked the debugger and are using it in screen mode. You now want to 
take advantage of the larger screen. The following command increases the 
screen height and width of the debugger window to 35 lines and 110 columns 
respectively: 


DBG> SET TERMINAL/PAGE:35/WIDTH:110 


By default, all displays are dynamic. A dynamic display automatically adjusts 
its window dimensions in proportion when a SET TERMINAL command 
changes the screen height or width. This means that, when using the SET 
TERMINAL command, you preserve the relative positions of your displays. The 
/[INOJDYNAMIC qualifier on the DISPLAY command enables you to control 
whether or not a display is dynamic. If a display is not dynamic, it does not 
change its window coordinates after you enter a SET TERMINAL command (you 


can then use the DISPLAY, MOVE, or EXPAND commands, or various keypad 


key combinations, to move or resize a display). 


To see the current terminal width and height being used by the debugger, use the 
SHOW TERMINAL command. 


Note that the debugger’s SET TERMINAL command does not affect the terminal 
screen size at DCL level. When you exit the debugger, the original screen size is 
maintained. 
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This chapter describes the following debugger convenience features not described 
elsewhere in this manual: 


¢ Using debugger command procedures 

e Using an initialization file for a debugging session 

e Logging a debugging session into a file 

¢ Defining symbols to represent commands, address expressions, or values 
e Assigning debugger commands to function keys 

¢ Using control structures to enter commands 


e Calling arbitrary routines linked with your program 


8.1 Using Debugger Command Procedures 


A debugger command procedure is a sequence of commands contained in a file. 
You can direct the debugger to execute a command procedure to re-create a 
debugging session, to continue a previous session, or to avoid typing the same 
debugger commands many times during a debugging session. You can pass 
parameters to command procedures. 


As with DCL command procedures, you execute a debugger command procedure 
by preceding its file specification with an at sign (@). The @ is the execute 
procedure command. 


Debugger command procedures are especially useful when you regularly perform 
a number of standard setup debugger commands, as specified in a debugger 
initialization file (see Section 8.2). You can also use a debugger log file as a 
command procedure (see Section 8.3). 


8.1.1 Basic Conventions 
The following is a sample debugger command procedure named BREAK7.COM: 


{ xx*k* Debugger Command Procedure BREAK7.COM ***** 

SET BREAK/AFTER:3 %LINE 120 DO (EXAMINE K,N,J,X(K); GO) 
SET BREAK/AFTER:3 %LINE 160 DO (EXAMINE K,N,J,X(K),S; GO) 
SET BREAK %SLINE 90 


When you execute this command procedure with the execute procedure (@) 
command, the commands listed in the procedure are executed in the order they 
appear. 


The rules entering commands in command procedures are listed in Section 1 of 
the command dictionary. 


You can pass parameters to a command procedure. See Section 8.1.2 for 
conventions on passing parameters. 


8-1 


Additional Convenience Features 
8.1 Using Debugger Command Procedures 


You can enter the @ command like any other debugger command—that is, directly 
from the terminal, from within another command procedure, from within a DO 
clause in a command such as SET BREAK, or from within a DO clause in a 
screen display definition. 


If you do not supply a full file specification with the @ command, the debugger 
assumes SYS$DISK:[ ]JDEBUG.COM as the default file specification for command 
procedures. For example, you would enter the following command line to execute 
command procedure BREAK7.COM, located in your current default directory: 


DBG> @BREAK7 


The SET ATSIGN command enables you to change any or all fields of the default 
file specification, SYS$DISK:[ JDEBUG.COM. The command SHOW ATSIGN 
identifies the default file specification for command procedures. 


By default, commands read from a command procedure are not echoed. If you 
enter the SET OUTPUT VERIFY command, all commands read from a command 
procedure are echoed on the current output device, as specified by DBGSOUTPUT 
(the default output device is SYS$OUTPUT). Use the SHOW OUTPUT command 
to determine whether commands read from a command procedure are echoed or 
not. 


If the execution of a command in a command procedure results in a diagnostic 
of severity "warning" or greater, the command is aborted, but execution of the 
command procedure continues at the next command line. 


8.1.2 Passing Parameters to Command Procedures 
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As with DCL command procedures, you can pass parameters to debugger 
command procedures. However, the technique is different in several respects. 


Subject to the conventions described here, you can pass as many parameters as 
you want to a debugger command procedure. The parameters can be address 
expressions, commands, or value expressions in the current language. You must 
surround command strings in quotation marks ("), and you must separate 
parameters by commas (, ). 


A debugger command procedure to which you pass parameters must contain a 
DECLARE command line that binds each actual (passed) parameter to a formal 
parameter (a symbol) declared within the command procedure. 


The DECLARE command is valid only within a command procedure. Its format 
is as follows: 


DECLARE p-name:p-kind{, p-name:p-kind[, .. . ]] 


Each p-name:p-kind pair associates a formal parameter (p-name) with a 
parameter kind (p-kind). The valid p-kind keywords are as follows: 

ADDRESS Causes the actual parameter to be interpreted as an address expression. 
COMMAND Causes the actual parameter to be interpreted as a command. 


VALUE Causes the actual parameter to be interpreted as a value expression in 
the current language. 


‘The following example illustrates what happens when a parameter is passed to 


a command procedure. The command DECLARE K:ADDRESS, within command 
procedure EXAM.COM, declares the formal parameter K. The actual parameter 
passed to EXAM.COM is interpreted as an address expression. The command 
EXAMINE K displays the value of that address expression. The command SET 
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OUTPUT VERIFY causes the commands to echo when they are read by the 
debugger. 


| ***** Debugger Command Procedure EXAM.COM ***** 
SET OUTPUT VERIFY 

DECLARE K:ADDRESS 

EXAMINE K 


The next command line executes EXAM.COM, passing the actual parameter 
ARR4. Within EXAM.COM, ARR4 is interpreted as an address expression (an 
array variable, in this case). 

DBG> @EXAM ARR4 


*DEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE K:ADDRESS 


EXAMINE K 
PROG_8\ARR4 
(1): 18 
(2): 1 
(3) 2 0 
(4): 1 
*DEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 


Each p-name:p-kind pair specified by a DECLARE command binds one parameter. 
So, for instance, if you want to pass five parameters to a command procedure, you 
need five corresponding p-name:p-kind pairs. The pairs are always processed in 
the order in which you specify them. 


For example, the next command procedure, EXAM_GO.COM accepts two 
parameters, an address expression (L) and a command string (M). The address 
expression is then examined and the command is executed: 


! ***x* Debugger Command Procedure EXAM GO.COM ***** 
DECLARE L:ADDRESS, M:COMMAND 
EXAMINE L; M 


The following example shows how you could execute EXAM_GO.COM, passing a 
variable X to be examined and a command @DUMP.COM to be executed: 


DBG> @EXAM GO X, “@DUMP" 


The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a command 
procedure. The value of %27PARCNT is the number of actual parameters passed to 
the command procedure. 


The %PARCNT built-in symbol is illustrated in the following example. The 
command procedure, VAR.DBG, contains the following lines: 


| *xkk* Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

! Display the number of parameters passed: 

EVALUATE %PARCNT 

! Loop as needed to bind all passed parameters and obtain their values: 
FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 


The following command line executes VAR.DBG, passing the parameters 12, 37, 
and 465: 
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DBG> @VAR.DBG 12,37, 45 

SDEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
! Display the number of parameters passed: 

EVALUATE sPARCNT 

3 


! Loop as needed to bind all passed parameters 

! and get their values: 

FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 
12 

37 

45 

$DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 
DBG> 


When VAR.DBG is executed, %PARCNT has the value 3. Therefore, the FOR 
loop within VAR.DBG is repeated 3 times. The FOR loop causes the DECLARE 
command to bind each of the three actual parameters (starting with 12) to a new 
declaration of X. Each actual parameter is interpreted as a value expression in 
the current language, and the EVALUATE X command displays that value. 


8.2 Using a Debugger Initialization File 


A debugger initialization file is a command procedure, assigned the logical 
name DBG$INIT, that the debugger automatically executes at debugger startup. 
Every time you invoke the debugger, the commands contained in the file are 
automatically executed. 


An initialization file contains any command lines you might always enter at 
the start of a debugging session to either tailor your debugging environment or 
control the execution of your program in a predetermined way from run to run. 


For example, you might have a file DEBUG_START4.COM containing the 
following commands: 


{ **x** Debugger Initialization File DEBUG START4.COM ***** 

! Log debugging session into default log file (SYSS$DISK: []DEBUG.LOG) 
SET OUTPUT LOG 

! 

! Echo commands as they are read from command procedures: 

SET OUTPUT VERIFY 

t 


! If source files are not in current default directory, use [SMITH.SHARE] 
SET SOURCE [], [SMITH.SHARE] 
{ 


! Invoke screen mode: 


SET MODE SCREEN 
! 


! Define the symbol SB as the SET BREAK command: 


DEFINE/COMMAND SB = "SET BREAK" 
! 


! Assign the SHOW MODULE * command to keypad key 7: 
DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 


To make this file a debugger initialization file, use the DCL command DEFINE. 
For example: 


$ DEFINE DBG$INIT WORK: [JONES.DBGCOMFILES] DEBUG START4.COM 
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8.3 Logging a Debugging Session into a File 


A debugger log file maintains a history of a debugging session. During the 
debugging session, each command entered and the resulting debugger output are 
stored in the file. 


The following is an example of a debugger log file. 


SHOW OUTPUT 

tnoverify, terminal, noscreen_log, logging to DSK2:[JONES.P7]DEBUG.LOG;1 
SET STEP NOSOURCE 

SET TRACE SLINE 30 

SET BREAK SLINE 60 

SHOW TRACE 

!tracepoint at PROG4\%LINE 30 

GO 

Itrace at PROG4\%LINE 30 

'preak at PROG4\%LINE 60 


The DBG> prompt is not recorded, and the debugger output is commented out 
with exclamation points so the file can be used as a debugger command procedure 
without modification. Thus, if a lengthy debugging session is interrupted, you 
can execute the log file as you would any other debugger command procedure. 
Executing the log file restores the debugging session to the point at which it was 
previously terminated. 


To create a debugger log file, use the SET OUTPUT LOG command. By default, 
the debugger writes the log to SYS$DISK:[ ]DEBUG.LOG. To name a debugger 
log file, use the SET LOG command. You can override any field of the default file 
specification. For example, after you enter the following commands, the debugger 
logs the session to the file [JONES.WORK2]MONITOR.LOG: 


DBG> SET LOG [JONES.WORK2]MONITOR 
DBG> SET OUTPUT LOG 


You might want to enter the SET OUTPUT LOG command in your debugger 
initialization file (see Section 8.2). 


The SHOW LOG command reports whether the debugger is writing to a log file 
and identifies the current log file. The SHOW OUTPUT command identifies all 
current output options. 


If you are debugging in screen mode, the SET OUTPUT SCREEN_LOG command 
enables you to log the screen contents as the screen is updated. To use this 
command, you must already be logging your debugging session—that is, the SET 
OUTPUT SCREEN_LOG command is valid only after you have entered the SET 
OUTPUT LOG command. Note that using SET OUTPUT SCREEN_LOG is not 
desirable for a long debugging session, because storing screen information in 
this manner results in a big log file. For other techniques on saving screen-mode 
information, see also the descriptions of the SAVE and EXTRACT commands in 
Chapter 7 and in the command dictionary. 


If you plan to use a log file as a command procedure, you should first enter the 
SET OUTPUT VERIFY command so that debugger commands are echoed as they 
are read. 
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8.4 Defining Symbols for Commands, Address Expressions, and 


Values 


The DEFINE command enables you to create a symbol for a lengthy or often- 
repeated command sequence or address expression and to store the value of a 
language expression in a symbol. 


You specify the kind of symbol you want to define by the command qualifier you 
use with the DEFINE command ((COMMAND, /ADDRESS, or /VALUE). The 
default qualifier is /ADDRESS. If you plan to enter several DEFINE commands 
with the same qualifier, you can first use the SET DEFINE command to establish 
a new default qualifier (for example, SET DEFINE COMMAND makes the 
DEFINE command behave like DEFINE/COMMAND). The SHOW DEFINE 
command identifies the default qualifier currently in effect. 


Use the SHOW SYMBOL/DEFINED command to identify symbols you have 


defined with the DEFINE command. Note that the SHOW SYMBOL command 
without the /DEFINED qualifier identifies only the symbols that are defined in 
your program, such as the names of routines and variables. 


Use the DELETE command to DELETE symbol definitions created with the 
DEFINE command. 


When defining a symbol within a command procedure, use the /LOCAL qualifier 
to confine the symbol definition to that command procedure. 


8.4.1 Defining Symbols for Commands 
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Use the DEFINE/COMMAND command to equate one or more commands 
(actually, strings) to a shorter symbol. The basic syntax is illustrated in the 
following example. 


DBG> DEFINE/COMMAND SB = "SET BREAK" 
DBG> SB PARSER 


In the example, the DEFINE/COMMAND command equates the symbol SB 

to the string SET BREAK (note the use of the quotation marks to delimit the 
command string). When the command line SB PARSER is executed, the debugger 
substitutes the string SET BREAK for the symbol SB and then executes the SET 
BREAK command. 


In the following example, the DEFINE/COMMAND command equates the symbol 
BT to the string consisting of the SHOW BREAK command followed by the 
SHOW TRACE command(use semicolons to separate multiple command strings): 


DBG> DEFINE/COMMAND BT = "SHOW BREAK;SHOW TRACE" 


The SHOW SYMBOL/DEFINED command identifies the symbol BT as follows: 


DBG> SHOW SYM/DEFINED BT 

defined BT 
bound to: "SHOW BREAK;SHOW TRACE" 
was defined /command 

DBG> 


To define complex commands, you might need to use command procedures with 
parameters (see Section 8.1.2 for information about passing parameters to 
command procedures). For example: 


DBG> DEFINE/COMMAND DUMP = "@DUMP_PROG2.COM" 
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8.4.2 Defining Symbols for Address Expressions 


Use the DEFINE/ADDRESS command to equate an address expression to a 
symbol. Although /ADDRESS is the default qualifier for the DEFINE command, 
it is used in the following examples for emphasis. 


In the following example, the symbol B1 is equated to the address of line 378; the 
SET BREAK B1 command then sets a breakpoint on line 378. 


DBG> DEFINE/ADDRESS Bl = %LINE 378 
DBG> SET BREAK Bl 


The DEFINE/ADDRESS command is useful when you need to specify a long path 
name repeatedly to reference the name of a variable or routine that is defined 
multiple times. In the next example, the symbol UX is equated to the path name 
SCREEN_IO\ UPDATE\X; the abbreviated command line EXAMINE UX can 
then be used to obtain the value of X in routine UPDATE of module SCREEN_IO. 


DBG> DEFINE UX = SCREEN _IO\UPDATE\X 
DBG> EXAMINE UX 


8.4.3 Defining Symbols for Values 


Use the DEFINE/VALUE command to equate the current value of a language 
expression to a symbol (the current value is the value at the time the DEFINE 
/VALUE command was entered). 


The following example illustrates how the DEFINE/VALUE command can be used 
to count the number of calls to a routine. 


DBG> DEFINE/VALUE COUNT = 0 
DBG> SET TRACE/SILENT ROUT DO (DEFINE/VALUE COUNT = COUNT + 1) 
DBG> GO 


DBG> EVALUATE COUNT 
14 
DBG> 


In the example, the first DEFINE/VALUE command initializes the value of the 
symbol COUNT to 0. The SET TRACE command sets a silent tracepoint on 
routine ROUT and (through the DO clause) increments the value of COUNT by 1 
every time ROUT is called. After execution is resumed and eventually suspended, 
the EVALUATE command obtains the current value of COUNT (the number of 
times that ROUT was called). 


8.5 Assigning Commands to Function Keys 


To facilitate entering commonly used commands, the function keys on the keypad 
have predefined debugger functions that are established when you invoke the 
debugger. These predefined functions are identified in detail in Appendix B. You 
can modify the functions of the keypad keys to suit your individual needs. If 
you have a VT200- or VT300-series terminal or a workstation, you can also bind 
commands to the additional function keys on the LK201 keyboard. 


The debugger commands DEFINE/KEY, SHOW KEY, and DELETE/KEY enable 
you to assign, identify, and delete key definitions, respectively. Before you can 
use this feature, keypad mode must be enabled with the SET MODE KEYPAD 
command (keypad mode is enabled by default). Keypad mode also enables you to 
use the predefined functions of the keypad keys. 
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If you want to use the keypad keys to enter numbers rather than debugger 
commands, enter the SET MODE NOKEYPAD command. 


8.5.1 Basic Conventions 


The debugger DEFINE/KEY command, which is similar to the DCL DEFINE 
/KEY command, enables you to assign a string to a function key. In the following 
example, the DEFINE/KEY command defines keypad key 7 to enter and execute 
the SHOW MODULE * command: 

DBG> DEFINE/KEY/TERMINATE KP7 "SHOW MODULE *" 


SDEBUG-I-DEFKEY, DEFAULT key KP7 has been defined 
DBG> 


The /TERMINATE qualifier indicates that pressing key 7 executes the command. 
You do not have to press Return after pressing key 7. 


KP7 is the key name that you must use with the commands DEFINE/KEY, 
SHOW KEY, and DELETE/KEY. The valid key names that you can use with 
these commands are listed in the command dictionary for VT52 and VT100-series 
terminals and for LK201 keyboards (see the command descriptions). 


The same function key can be assigned any number of definitions as long 
as each definition is associated with a different state. The predefined states 
(DEFAULT, GOLD, BLUE, and so on) are identified in Appendix B. In the 
preceding example, the informational message indicates that key 7 has been 
defined for the DEFAULT state (which is the default key state). 


You can enter key definitions in a debugger initialization file (see Section 8.2) so 
that these definitions are available whenever you invoke the debugger. 


To display a key definition in the current state, enter the SHOW KEY command. 
For example: 

DBG> SHOW KEY KP7 

DEFAULT keypad definitions: 


KP7 = "SHOW MODULE *" (echo, terminate, nolock) 
DBG> 


To display a key definition in a state other than the current state, specify that 
state with the /STATE qualifier when entering the SHOW KEY command. To see 
all key definitions in the current state, enter the SHOW KEY/ALL command. 


To delete a key definition, use the DELETE/KEY command. To delete a key 
definition in a state other than the current state, specify that state with the 
/STATE qualifier. For example: 


DBG> DELETE/KEY/STATE=GOLD KP7 
SDEBUG-I-DELKEY, GOLD key KP7 has been deleted 
DBG> 

8.5.2 Advanced Techniques 


This section illustrates more advanced techniques for defining keys, particularly 
techniques related to the use of state keys. 


The following command line assigns the unterminated command string "SET 
BREAK %LINE" to keypad key 9, for the BLUE state. 


DBG> DEFINE/KEY/IF STATE=BLUE KP9 "SET BREAK ®LINE" 
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The predefined DEFAULT key state is established by default. The predefined 
BLUE key state is established by pressing the PF4 key. You would enter the 
command line assigned in the preceding example (SET BREAK %LINE ... ) by 
pressing key PF4, pressing KP9, entering a line number, and then pressing the 
Return key to terminate and process the command line. 


The SET KEY command enables you to change the default state for key 
definitions. For example, after entering the SET KEY/STATE=BLUE command, 
you would not need to press PF4 to enter the command line in the previous 
example. Also, the SHOW KEY command would show key definitions in the 
BLUE state, by default, and the DELETE/KEY command would delete key 
definitions in the BLUE state by default. 

You can create additional key states. For example: 

DBG> SET KEY/STATE=DEFAULT 

DBG> DEFINE/KEY/SET_STATE=RED/LOCK_STATE Bia 


In this example, the SET KEY command establishes DEFAULT as the current 
state. The DEFINE/KEY command makes key F12 (LK201 keyboard) a state key. 
As a result, pressing F12 while in the DEFAULT state causes the current state to 
become RED. The key definition is not terminated and has no other effect (a null 
string is assigned to F12). After pressing F12, you can enter "RED" commands 
by pressing keys that have definitions associated with the RED state. 


8.6 Using Control Structures to Enter Commands 


The FOR, IF, REPEAT, and WHILE commands enable you to create looping and 
conditional constructs for entering debugger commands. The associated command 
EXITLOOP is used to exit a FOR, REPEAT, or WHILE loop. 


See Section 4.1.5 and Section 9.3.2.2 for information about evaluating language 
expressions. 


8.6.1 FOR Command 


The FOR command executes a sequence of commands while incrementing a 
variable a specified number of times. It has the following format: 


FOR name=expression! TO expression2 [BY expression3] DO(command; . . . }) 


For example, the following command line sets up a loop that initializes the first 
10 elements of an array to zero: 


DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 


8.6.2 IF Command 


The IF command executes a sequence of commands if a language expression 
(Boolean expression) is evaluated as true. It has the following format: 


IF boolean-expression THEN (command; . . . ]) [ELSE (command{; . . . })] 


The following FORTRAN example sets up a condition that issues the command 
EXAMINE X2 if X1 is not equal to —9.9, and issues the command EXAMINE Y1 
otherwise: 


DBG> IF Xl .NE. -9.9 THEN (EXAMINE X2) ELSE (EXAMINE Y1) 


The following Pascal example combines a FOR loop and a condition test. The 
STEP command is issued if X1 is not equal to —9.9. The test is made four times: 


DBG> FOR COUNT = 1 TO 4 DO (IF Xl <> -9.9 THEN (STEP) ) 
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8.6.3 REPEAT Command 


The REPEAT command executes a sequence of commands a specified number of © 
times. It has the following format: 


REPEAT /anguage-expression DO (command; .. . }) 


For example, the following command line sets up a loop that issues a sequence of 
two commands (EXAMINE Y then STEP) 10 times: 


DBG> REPEAT 10 DO (EXAMINE Y; STEP) 


8.6.4 WHILE Command 


The WHILE command executes a sequence of commands while the language 
expression (Boolean expression) you have specified evaluates as true. It has the 
following format: 


WHILE boolean-expression DO (command; . . . ]) 


The following Pascal example sets up a loop that tests X1 and X2 repetitively and 
issues the two commands EXAMINE X2 and STEP if X2 is less than X1: 


DBG> WHILE X2 < X1 DO (EX X2;STEP) 


8.6.5 EXITLOOP Command 


The EXITLOOP command exits one or more enclosing FOR, REPEAT, or WHILE 
loops. It has the following format: 


EXITLOOP [n] 
The integer n specifies the number of nested loops to exit from. 


The following Pascal example sets up an endless loop that issues a STEP 
command with each iteration. After each step, the value of X is tested. If X is 
greater than 3, the EXITLOOP command terminates the loop. 


DBG> WHILE TRUE DO (STEP; IF X > 3 THEN EXITLOOP) 


8.7 Calling Routines Independently of Program Execution 
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The CALL command enables you to execute a routine independently of the 
normal execution of your program. It is one of the four debugger commands that 
can be used to execute your program (the others are GO, STEP, and EXIT). 


The CALL command executes a routine whether or not your program actually 
includes a call to that routine, so long as the routine was linked with your 
program. Thus you can use the CALL command to execute routines for any 
purpose (for example, to debug a routine out of the context of program execution, 
invoke a run-time library procedure, execute a routine that dumps debugging 
information, and so on). 


You can debug unrelated routines by linking them with a dummy main program 
that has a transfer address, and then using the CALL command to execute them. 


The following example shows how you could use the CALL command to display 
some process statistics without having to include the necessary code in your 
program. The example consists of calls to run-time library routines that initialize 
a timer (LIB$INIT_TIMER) and display the elapsed time and various statistics 
(LIB$SHOW_TIMER). (Note that the presence of the debugger affects the timings 
and counts.) 
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DBG> SET MODULE SHARESLIBRTL @ 
DBG> CALL LIBSINIT_TIMER 


value returned is 1 © 
DBG> [ enter various debugger commands ] 


DBG> CALL LIBSSHOW TIMER @ 

ELAPSED: 0 00:00:21.65 CPU: 0:14:00.21 BUFIO: 16 DIRIO: 0 FAULTS: 3 
value returned is l 

DBG> 


The comments that follow refer to the callouts in the previous example: 


@ Routines LIB$INIT_TIMER and LIB$SHOW_TIMER are in the shareable 
image LIBRTL. This image must be set by setting its "module" because 
only its universal symbols are accessible during a debugging session (see 
Section 5.4.2.3). 


@ This CALL command executes routine LIB$INIT_TIMER. 


© The "value returned" message indicates the value returned in register RO 
after the CALL command has been executed. 


By VMS convention, after a called routine has executed, register RO contains 
the function return value (if the routine is a function) or the procedure 
completion status (if the routine is a procedure that returns a status value). 
If a called procedure does not return a status value or function value, the 
value in RO might be meaningless, and the "value returned" message can be 
ignored. 


@ This CALL command executes routine LIB${SHOW_TIMER. 


The following example shows how to call LIBS{SHOW_VM (also in LIBRTL) to 
display memory statistics. (Again, note that the presence of the debugger affects 
_ the counts): 
DBG> SET MODULE SHARESLIBRTL 
DBG> CALL LIBSSHOW VM 

1785 calls to LIBSGET VM, 284 calls to LIBSFREE_ VM, 


122216 bytes still allocated value returned is 1 
DBG> , 


You can pass parameters to routines with the CALL command. See the 
description of the CALL command in the command dictionary for details 
and examples. 
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Debugging Special Cases 


This chapter presents debugging techniques for special cases that are not covered 
elsewhere in this manual: 


¢ Optimized code 

e Screen-oriented programs 

¢ Multilanguage programs 

¢ Exceptions and condition handlers 
e Exit handlers 

¢ AST-driven programs 


9.1 Debugging Optimized Code 


By default, many compilers optimize the code they produce so that the program 
executes faster. The net result is that the code that is executing as you debug 
might not match the source code displayed in a screen-mode source display 
(see Section 7.2.1) or in a source listing file. For example, some optimization 
techniques eliminate variables so that you no longer have access to them while 
debugging. 


To avoid the problems of debugging optimized code, many compilers allow you 
to specify the /NOOPTIMIZE (or equivalent) command qualifier at compile 
time. Specifying this qualifier inhibits most compiler optimization, thereby 
reducing discrepancies between the source code and executable code caused by 
optimization. 


If this option is not available to you, read this section. It describes the techniques 
for debugging optimized code and gives some typical examples of optimized code 
to illustrate the potential causes of confusion. 


When debugging optimized code, use a screen-mode instruction display, such 
as the predefined display INST, to show the decoded VAX assembly-language 
instruction stream of your program (see Section 7.2.4). An instruction display 
shows the exact code that is executing. 


In screen mode, pressing keypad key KP7 places the SRC and INST displays side 
by side for easy comparison. Alternatively, you can inspect a compiler-generated 
machine code listing. 


In addition, to execute the program at the instruction level and examine 
instructions, use the techniques described in Section 4.3. 


Using these methods, you should be able to determine what is happening at the 
executable code level and thereby resolve the discrepancy between source display — 
and program behavior. 
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9.1.1 Eliminated Variables 
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A compiler might optimize code by eliminating variables, either permanently or 
temporarily at various points during execution. If you try to examine a variable 
X that no longer is accessible because of optimization, the debugger might display 
one of the following messages: 


SDEBUG-W-UNALLOCATED, entity X was not allocated in memory 
(was optimized away) 


SDEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC (was optimized away) 


The following Pascal example shows how this could happen: 


PROGRAM DOC (OUTPUT) ; 
VAR 
X,Y: INTEGER; 
BEGIN 
MoS SF 
Y 3= 2; 
WRITELN 
END. 


(X*Y); 


If you compile this program with the /NOOPTIMIZE (or equivalent) qualifier, you 
obtain the following (normal) behavior when debugging: 


$ PASCAL/DEBUG/NOOPTIMIZE DOC 
$ LINK/DEBUG DOC 


$ RUN DOC 

DBG> STEP 

stepped to DOC\SLINE 5 
as x. t= 5) 

DBG> STEP 

stepped to DOC\SLINE 6 
be Y a2> 

DBG> STEP 


aes to DOC\%LINE 7 
WRITELN (X*Y); 
DBG> palit X,Y 


DOC\X: 5 
poc\y: 2 
DBG> 


If you compile the program with the /OPTIMIZE (or equivalent) qualifier, because 
the values of X and Y are not changed after the initial assignment, the compiler 
calculates X*Y, stores that value (10), and does not allocate storage for X or Y. 
Therefore, after you invoke the debugger, a STEP command takes you directly to 
line 7 rather than line 5. Moreover, you cannot examine X or Y: 


$ PASCAL/DEBUG/OPTIMIZE DOC 
$ LINK/DEBUG DOC 
$ RUN DOC 


DBG> EXAMINE X,Y 
SDEBUG-W-NOVALATPC, entity X does not have a value at the 
current PC (was optimized away) 
DBG> STEP 
ae to DOC\SLINE 7 
WRITELN (X*Y) ; 
DBG> 
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To see what values are being used in your optimized program, use the command 
EXAMINE/OPERAND .%PC to display the machine code at the current PC value, 
including the values and symbolization of all of the operands. For example, the 
following lines show the optimized code when the PC value is at the WRITELN 
statement: 


DBG> STEP 
stepped to DOC\%LINE 7 

as WRITELN (X*Y); 
DBG> EXAMINE/OPERAND .%PC 
DOC\SLINE 7: PUSHL S*#10 
DBG> 


In contrast, the following lines show the unoptimized code at the WRITELN 
statement: 


DBG> STEP 
stepped to DOC\S%LINE 7 
Ps WRITELN (X*Y) ; 
DBG> EXAMINE/OPERAND .%PC 
DOC\%LINE 7: MOVL S*#10,B*-4 (FP) 
B*-4 (FP) 2146279292 contains 62914576 
DBG> 


9.1.2 Changes in Coding Order 


Several methods of optimizing consist of performing operations in a sequence 
different from the sequence specified in the source code. Sometimes code is 
eliminated altogether. 


As a result, the source code displayed by the debugger does not correspond exactly 
to the actual code being executed. 


To illustrate, the following example depicts a segment of source code from a 
FORTRAN program as it might appear on a compiler listing or in a screen-mode 
source display. This code segment sets the first 10 elements of array A to the 


value 1/X. 

Line ; Source Code 
5 DO 100 I=1,10 
6 A(I) = 1/x 
7 100 CONTINUE 


As the compiler processes the source program, it determines that the reciprocal of 
X need only be computed once, not 10 times as the source code specifies, because 
the value of X never changes in the DO-loop. The compiler thus generates 
optimized code equivalent to the following code segment: 


Line Optimized Code Equivalent 
5 TEMP = 1/X 
DO 100 I=1,10 
6 A(I) = TEMP 
7 100 CONTINUE 


In the optimized code, the value of 1/X is computed once, saved in a temporary 
location, and then assigned to each A(I). The optimized code now executes faster, 
but it no longer corresponds exactly to the source code. 


In this example, if you execute to line 5 by entering a STEP command, the 
debugger displays the source line as it appears in the source file, not the 
optimized code equivalent that it is actually executing. 
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stepped to PROG \S%LINE 5 
ie DO 100 I=1,10 


At this point, if you enter another STEP command to execute line 5, the debugger 
executes line 5 of the optimized code, not line 5 of the displayed source code. 
Thus, the program computes the reciprocal of X and sets up the DO loop, whereas 
the source display indicates only that the DO loop is set up. 


This discrepancy is not obvious from looking at the displayed source line. 
Furthermore, if the computation of 1/X were to fail because X is zero, it would 
appear from inspecting the source display that a division by zero had occurred on 
a source line that contains no division at all. 


This kind of apparent mismatch between source code and executable code should 
be expected from time to time when debugging optimized programs. It can be 
caused not only by code motions out of loops, as in the previous example, but by a 
number of other optimization methods as well. 


9.1.3 Use of Registers 


A compiler might determine that the value of an expression does not change 
between two given occurrences and might save the value in a register. In such 
cases, the compiler does not recompute the value for the next occurrence, but 
assumes the value saved in the register is valid. 


If, while debugging a program, you use the DEPOSIT command to change the 
value of the variable in the expression, the corresponding value stored in the 
register might not be changed. Thus, when execution continues, the value in the 
register might be used instead of the changed value in the expression, causing 
unexpected results. 


In addition, when the value of a nonstatic variable (see Section 3.6.2) is held in 
a register, its value in memory is generally invalid; therefore, a spurious value 
might be displayed if you enter the EXAMINE command for a variable under 
these circumstances. 


9.1.4 Use of Condition Codes 
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One optimization technique takes advantage of the way in which the VAX 
processor condition codes are set. For example, consider the following Pascal 
source code: 

A OK 2a OF 


IF X < 0 
THEN 


Rather than test the new value of X to determine whether to branch, the 
optimized code bases its decision on the condition code setting after 2.5 is added 
to X. Thus, if you attempt to set a breakpoint on the IF statement and deposit 
a different value into X, you do not achieve the intended result because the 
condition codes no longer reflect the value of X. In other words, the decision to 
branch is being made without regard to the deposited value of the variable. 


Again, you can use the EXAMINE/OPERAND .%PC command to determine the 
correct location for depositing so as to achieve the desired effect. 
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9.2 Debugging Screen-Oriented Programs 


The debugger uses the terminal screen for input and output (I/O) during a 
debugging session. If you use a single terminal to debug a screen-oriented 
program that uses most or all of the screen, debugger I/O can overwrite, or can be 
overwritten by, program I/O. 


Using one terminal for both program I/O and debugger I/O is even more 
complicated if you are debugging in screen mode and your screen-oriented 
program calls any VMS RTL Screen Management (SMG$) routines. This is 
because the debugger’s screen mode also calls SMG routines. In such cases, the 
debugger and your program share the same SMG pasteboard, causing further 
interference. 


To avoid these problems when debugging a screen-oriented program, use one of 
the following techniques to separate debugger I/O from program I/O: 


e Ifyou are at a workstation running VWS, start your debugging session and 
then enter the debugger command SET MODE SEPARATE. It creates a 
separate terminal-emulator window for debugger I/O. Program I/O continues 
to be displayed in the window from which you invoked the debugger. 


e Ifyou are at a workstation running DECwindows and want to display the 
debugger’s DECwindows interface on a separate workstation (also running 
DECwindows), see Section -1.6.3.1. 


e Ifyou are at a workstation running DECwindows but want to use the 
debugger’s command interface rather than the DECwindows interface, see 
Section 1.6.3.3. It explains how to create a separate DECterm window 
for debuger I/O. The effect is similar to using the command SET MODE 
SEPARATE on a workstation running VWS. 


¢ If you do not have a workstation, use two terminals—one for program I/O 
and another for debugger I/O. The technique is described in the rest of this 
section. 


Assume that TTD1: is your current terminal, from which you plan to invoke the 
debugger. You want to display debugger I/O on terminal TTD2: so that TTD1: is 
devoted exclusively to program I/O. 


Follow these steps: 


1. Provide the necessary protection to TTD2: so that you can allocate that 
terminal from TTD1: (see Section 9.2.1). 
The remaining steps are all performed from TTD1:. 

2. Allocate TTD2:. This provides your process on TTD1: with exclusive access to 
TTD2:: 
$ ALLOCATE TTD2: 

3. Assign the debugger logical names DBG$INPUT and DBG$OUTPUT to 
TTD2:: 
$ DEFINE DBGSINPUT TTD2: 
$ DEFINE DBGSOUTPUT TTD2: 
DBG$INPUT and DBG$OUTPUT specify the debugger input device and 
output device, respectively. By default, these logical names are equated to 
SYS$INPUT and SYS$OUTPUT, respectively. Assigning DBG$INPUT and 
DBG$OUTPUT to TTD2: enables you to display debugger commands and 
debugger output on TTD2:. 
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4. Make sure that the terminal type is known to the system. Use the following 


command: ; 
$ SHOW DEVICE/FULL TTD2: 
If the device type is "unknown," your system manager (or a user with LOG_ 


IO or PHY_IO privilege) must make it known to the system as shown in the 
following example. In the example, the terminal is assumed to be a VT200: 


$ SET TERMINAL/PERMANENT/DEVICE=VT200 TTD2: 


Run the program to be debugged: 
$ RUN FORMS 
You can now observe debugger I/O on TTD2: 


When finished with the debugging session, deallocate TTD2: as follows (or log 
out): 


$ DEALLOCATE TTD2: 


9.2.1 Setting the Protection to Allocate a Terminal 


On a properly secured system, terminals are protected so that you cannot allocate 
a terminal from another terminal. 


To set the nessary protection, your system manager (or a user with the privileges 
indicated) should follow the steps illustrated in the following example. 


In the example, TTD1: is your current terminal (from which you plan to invoke 
the debugger), and TTD2: is the terminal to be allocated so that it can display 
debugger I/O. 


1. 


If both TTD1: and TTD2: are hardwired to the system, go to step 4. 


If TTD1: and TTD2: are connected to the system over a LAT (local area 
transport), continue with step 2. 


Log in to TTD2: 


Enter these commands (you need LOG_IO or PHY_IO privilege): 


$ SET PROCESS/PRIV=LOG 10 
$ SET TERMINAL/NOHANG/PERMANENT 
§ LOGOUT/NOHANG 


4, Enter one of the following commands (you need OPER privilege): 


$ SET ACL/OBJECT_TYPE=DEVICE/ACL=(IDENT=[PROJ, JONES] ,ACCESS=READ+WRITE) TTD2: @ 
$ SET PROTECTION=WORLD:RW/DEVICE TTD2: @ 


@ The SET ACL command line is preferred because it uses an access control 
list (ACL). In the example, access is restricted to UIC [PROJ,JONES]. 


@ The SET PROTECTION command line provides world read/write access 
and, therefore, allows any user to allocate and perform I/O to TTD2:. 


9.3 Debugging Multilanguage Programs 


The debugger enables you to debug modules whose source code is written in 
different languages, within the same debugging session. This section highlights 
some language-specific behavior that you should be aware of, to minimize possible 
confusion. 
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When debugging in any language, be sure to consult 
¢ Appendix E, which summarizes debugger support for each language. 
¢ The documentation supplied with that language. 


9.3.1 Controlling the Current Debugger Language 


At debugger startup, the debugger sets the current language to that in which 
the module containing the main program (usually the routine containing the 
image transfer address) is written. The current language is identified when you 
invoke the debugger. For example: 


$ RUN FORMS 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is PASCAL, module set to FORMS 
DBG> 


The current language setting determines how the debugger parses and interprets 
the names, operators, and expressions you specify in debugger commands, 
including things like the typing of variables, array and record syntax, the default 
radix for integer data, case sensitivity, and so on. The language setting also 
determines how the debugger displays data associated with your program. 


Many programs include modules that are written in languages other than that 
of the main program. To minimize confusion, by default the debugger language 
remains set to the language of the main program throughout a debugging session, 
even if execution is suspended within a module written in another language. 


To take full advantage of symbolic debugging with such modules, use the SET 
LANGUAGE command to set the debugging context to that of another language. 
For example, the following command causes the debugger to interpret any 
symbols, expressions, and so on according to the rules of the COBOL language: 


DBG> SET LANGUAGE COBOL 


The keywords that you can use with the SET LANGUAGE command correspond 
to all of the VMS supported languages that are also supported by the debugger: 


ADA 
BASIC 
BLISS 
C 
COBOL 
DIBOL 


SCAN 


In addition, when debugging a program that is written in an unsupported 
language, you can specify the SET LANGUAGE UNKNOWN command. To 
maximize the usability of the debugger with unsupported languages, the SET 
LANGUAGE UNKNOWN command causes the debugger to accept a large set of 
data formats and operators, including some that might be specific to only a few 
supported languages. The operators and constructs that are recognized when the 
language is set to UNKNOWN are identified in Appendix E. 
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9.3.2 Specific Differences Among Languages — 


This section lists some of the differences you should keep in mind when debugging 
in various languages. Included are differences that are affected by the SET 
LANGUAGE command and other differences (for example, language-specific 
initialization code and predefined breakpoints). 


This list is not intended to be complete. See Appendix E and your language 
documentation for complete details. 


9.3.2.1 Default Radix 


The default radix for entering and displaying integer data is hexadecimal for 
BLISS and MACRO and decimal for all other languages. 


Use the SET RADIX command to establish a new default radix. 


9.3.2.2 Evaluating Language Expressions 


Several debugger commands and constructs evaluate language expressions: 
¢ The EVALUATE, DEPOSIT, IF, FOR, REPEAT, and WHILE commands. 


e WHEN clauses, which are used with the SET BREAK, SET TRACE, and SET 
WATCH commands. 


When processing these commands, the debugger evaluates language expressions 
in the syntax of the current language and in the current radix as discussed in 
Section 4.1.5. 


Note that operators vary widely among different languages (see Appendix E). For 
example, the following two commands evaluate equivalent expressions in Pascal 
and FORTRAN, respectively: 


DBG> SET WATCH X WHEN (Y < 5) ! Pascal 
DBG> SET WATCH X WHEN (Y .LT. 5) ! FORTRAN 


Assume that the language is set to PASCAL and you have entered the first 
(Pascal) command. You now step into a FORTRAN routine, set the language to 
FORTRAN, and resume execution. While the language is set to FORTRAN, the 
debugger is not able to evaluate the expression (Y < 5). As a result, it sets an 
unconditional watchpoint and, when the watchpoint is triggered, returns a syntax 
error for the "<" operator. 


This type of discrepancy can also occur if you use commands that evaluate 
language expressions in debugger command procedures and initialization files. 


Note also that the debugger processes language expressions that contain variable 
names (or other address expressions) differently when the language is set to 
BLISS than when it is set to another language. See Section 4.1.5 for details. 


9.3.2.3 Arrays and Records 
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The syntax for denoting array elements and record components (if applicable) 
varies among languages. 


For example, some languages use brackets, [], and others use parentheses, (), to 
delimit array elements. 


Some languages (like BASIC) have zero-based arrays. Some languages have 
one-based arrays, as in the following example: 
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DBG> EXAMINE INTEGER ARRAY 
PROG2\INTEGER ARRAY 


(1,1): 27 

(1,2): 31 

parece Is 12 

(2,1): 15 

(252) 22 

(2,3): 18 
DBG> 


For some languages (like Pascal and Ada) the specific array declaration 
determines how the array is based. 


9.3.2.4 Case Sensitivity 
Names and language expressions are case sensitive in C. You must specify 
them exactly as they appear in the source code. For example, the following two 
commands are not equivalent when the language is set to C: 


DBG> SET BREAK SCREEN IO\%LINE 10 
DBG> SET BREAK screen _io\%LINE 10 


9.3.2.5 Initialization Code 
If you have a multilanguage program that includes an Ada package, or a 
FORTRAN main program that was compiled with the /CHECK=UNDERFLOW 
(or /CHECK=ALL) qualifier, a NOTATMAIN message is issued when you invoke 
the debugger. For example: 


$ RUN MONITOR 
VAX DEBUG Version 5.5 


sDEBUG-I-INITIAL, language is ADA, module set to MONITOR 
SDEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 


The NOTATMAIN message indicates that execution is suspended before the 
beginning of the main program. This enables you to execute and check some 
initialization code under debugger control. 


The initialization code is created by the compiler and is placed in a special 
PSECT named LIB$INITIALIZE. In the case of an Ada package, the initialization 
code belongs to the package body (which might contain statements to initialize 
variables, and so on). In the case of a FORTRAN program, the initialization code 
declares the handler that is needed if you specify the /CHECK=UNDERFLOW or 
/CHECK=ALL qualifier. 


The NOTATMAIN message indicates that, if you do not want to debug the 
initialization code, you can execute immediately to the beginning of the main 
program by entering a GO command. You are then at the same point as when 
you invoke the debugger with any other program. Entering the GO command 
again starts program execution. 


9.3.2.6 Ada Predefined Breakpoints 
If your program is linked with a module that is written in Ada, two breakpoints 
that are associated with Ada tasking exception events are automatically 
established when you invoke the debugger. Note that these breakpoints are 
not affected by a SET LANGUAGE command. They are established automatically 
during debugger initialization when the Ada Run-Time Library is present. When 
you enter a SHOW BREAK command under these conditions, the following 
breakpoints are displayed: 
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DBG> SHOW BREAK 
Predefined breakpoint on ADA event "EXCEPTION TERMINATED" for any value 


Predefined breakpoint on ADA event "DEPENDENTS EXCEPTION" for any value 
DBG> 


9.4 Debugging Exceptions and Condition Handlers 


A condition handler is a procedure that the VMS operating system executes when 
an exception occurs. 


Exceptions include hardware conditions (such as an arithmetic overflow or 
a memory access violation) or signaled software exceptions (for example, an 
exception signaled because a file could not be found). 


VMS conventions specify how, and in what order, various condition handlers 
established by the operating system, the debugger, or your own program are 
invoked—for example, the primary handler, call frame (application-declared) 
handlers, and so on. Section 9.4.3 describes condition handling when you 
are using the debugger. See the VMS Run-Time Library Routines Volume for 
additional general information about condition handling. 


Tools for debugging exceptions and condition handlers include the following: 


¢ The SET BREAK/EXCEPTION and SET TRACE/EXCEPTION commands, 
which direct the debugger to treat any exception generated by your 
- program as a breakpoint or tracepoint, respectively (see Section 9.4.1 
and Section 9.4.2). 


e Several built-in symbols (such as %EXC_NAME), which enable you to qualify 
exception breakpoints and tracepoints (see Section 9.4.4). 


e The SET BREAK/EVENT and SET TRACE/EVENT commands, which enable 
you to break on or trace exception events that are specific to Ada and SCAN 
programs (see the corresponding documentation for more information). 


9.4.1 Setting Breakpoints or Tracepoints on Exceptions 


When you enter a SET BREAK/EXCEPTION (or SET TRACE/EXCEPTION) 
command, you direct the debugger to treat any exception generated by 

your program as a breakpoint (or tracepoint). As a result of a SET BREAK 
/EXCEPTION command, if your program generates an exception, the debugger 
suspends execution, reports the exception and the line where execution is 
suspended, and prompts for commands. The following example illustrates the 
effect: 


DBG> SET BREAK/EXCEPTION 


DBG> GO 


SSYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
break on exception preceding TEST\%LINE 13 
6: 


DBG> 
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X := 3/Y; 


Note that an exception breakpoint (or tracepoint) is triggered even if your 

program has a condition handler to handle the exception. The SET BREAK 
/EXCEPTION command causes a breakpoint to occur before any handler can 
execute (and thereby possibly dismiss the exception). Without the exception 


‘breakpoint, the handler would be executed, and the debugger would get control 


only if no handler dismissed the exception (see Section 9.4.2 and Section 9.4.3). 
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The following command line is useful for identifying where an exception occurred. 
It causes the debugger to display automatically the sequence of active calls and 
the PC value at an exception breakpoint. 


DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 


You can also create a screen-mode DO display that issues a SHOW CALLS 
command whenever the debugger interrupts execution. For example: 


DBG> DISPLAY CALLS DO (SET MODULE/CALLS; SHOW CALLS) 


An exception tracepoint (established with the SET TRACE/EXCEPTION 
command) is like an exception breakpoint followed by a GO command without an 
address expression specified. 


An exception breakpoint cancels an exception tracepoint, and vice versa. 


To cancel exception breakpoints or tracepoints, use the CANCEL BREAK 
/EXCEPTION or CANCEL TRACE/EXCEPTION command, respectively. 


9.4.2 Resuming Execution at an Exception Breakpoint 


When an exception breakpoint is triggered, execution is suspended before any 
application-declared condition handler is invoked. When you resume execution 
from the breakpoint with the GO, STEP, or CALL commands, the behavior is as 
follows: 


e Entering a GO command without an address-expression parameter, or 
entering a STEP command, causes the debugger to resignal the exception. 
The GO command enables you to observe which application-declared handler, 
if any, next handles the exception. The STEP command causes you to step 
into that handler (see the next example). 


e Entering a GO command with an address-expression parameter causes 
execution to resume at the specified location, thus inhibiting the execution of 
any application-declared handlers. 


¢ A common debugging technique at an exception breakpoint is to call a dump 
routine with the CALL command (see Chapter 8). When you enter the 
CALL command at an exception breakpoint, no breakpoints, tracepoints, or 
watchpoints that were previously set within the called routine are active, so 
that the debugger does not lose the exception context. After the routine has 
executed, the debugger prompts for input. Entering a GO or STEP command 
at this point causes the debugger to resignal the exception, as for the first 
bulleted item in this list. 


The following FORTRAN example shows how to determine the presence of a 
condition handler at an exception breakpoint and how a STEP command, entered 
at the breakpoint, enables you to step into the handler. 


At the exception breakpoint, the SHOW CALLS command indicates that the 
exception was generated during a call to routine SYS$QIOW: 
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DBG> SET BREAK/EXCEPTION 
DBG> GO 


SSYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000 
break on exception preceding SYSSQIOW+6 
DBG> SHOW CALLS 


module name routine name line rel PC abs PC 
SYSSQIOW 00000006 7FFEDE06 

*EXCSMAIN EXCSMAIN 23 0000003B 00000638 

DBG> 


The following SHOW STACK command indicates that no handler is declared in 
routine SYS$QIOW. However, one level down the call stack, routine EXC$MAIN 
has declared a handler named SSHAND: 


DBG> SHOW STACK 
stack frame 0 (2146296644) 
condition handler: 0 


SPA: 0 
S: 0 
mask: “M<R2,R3,R4,R5,R6,R7,R8,R9,R10,R11> 
PSW: 0020 (hexadecimal) 
saved AP: 2146296780 
saved FP: 2146296704 


saved PC: EXCSMAIN\SLINE 25 


stack frame 1 (2146296704) 
condition handler: SSHAND 


SPA: 0 

S: 0 

mask: “M<R11> 

PSW: 0000 (hexadecimal) 
saved AP: 2146296780 
saved FP: 2146296760 


saved PC: SHARESDEBUG+2217 


At this exception breakpoint, entering a STEP command enables you to step 
directly into condition handler SSHAND: 


DBG> STEP 
stepped to routine SSHAND 
fm INTEGER*4 FUNCTION SSHAND (SIGARGS, MECHARGS) 

DBG> SHOW CALLS 
module name routine name line rel PC abs PC 
* SSHAND SSHAND 2 00000002 00000642 
aso above condition handler called with exception 0000045C: 
SSYSTEM-F-SSFAIL, system service failure exception, status=0000013C, PC=7FFEDE06, PSL=03C00000 
Saas end of exception message 

SYSSQIOW 00000006 T7FFEDE06 
*EXCSMAIN EXCSMAIN Z3 0000003B 0000063B 
DBG> 


The debugger symbolizes the addresses of condition handlers into names if that 
is possible. However, note that with some languages, exceptions are first handled 
by an RTL routine, before any application-declared condition handler is invoked. 
In such cases, the address of the first condition handler might be symbolized to 
an offset from an RTL shareable image address. 
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9.4.3 Effect of Debugger on Condition Handling 


When you run your program with the debugger, at least one of the following 
condition handlers is invoked, in the order given, to handle any exceptions caused 
by the execution of your program: 


1. Primary handler. 

2. Secondary handler. 

3. Call-frame handlers (application-declared). Also known as stack handlers. 

4, Final handler. 

5. Last-chance handler. 

6. Catchall handler. 

A handler can return one of the following three status codes to the VAX Condition 
Handling Facility: 

¢ SS$_RESIGNAL—The VMS operating system searches for the next handler. 


e SS$ CONTINUE—The condition is assumed to be corrected, and execution 
continues. 


e SS$ UNWIND—The call stack is unwound some number of frames, if 
necessary, and the signal is dismissed. 


For more information about condition handling, see the VMS Run-Time Library 
Routines Volume. 


9.4.3.1 Primary Handler 


When you run your program with the debugger, the primary handler is the 
debugger. Therefore, the debugger has the first opportunity to handle an 
exception, whether or not the exception is caused by the debugger (Section 3.7 
describes how the debugger causes exceptions to occur in your program in order 
to control and monitor execution). 


If you have entered a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION 
command, the debugger breaks on (or traces) any exceptions caused by your 
program. The break (or trace) action occurs before any application-declared 
handler is invoked. 


If you have not entered a SET BREAK/EXCEPTION or SET TRACE/EXCEPTION 
command, the primary handler resignals any exceptions caused by your program. 


9.4.3.2 Secondary Handler 


The secondary handler is used for special purposes and does not apply to the 
types of programs covered in this manual. 


9.4.3.3 Call-Frame Handlers (Application-Declared) 
Each routine of your program can establish a condition handler, also known as 
a call-frame handler. The operating system searches for these handlers starting 
with the routine that is currently executing. If no handler was established for 
that routine, the system searches for a handler established by the next routine 
down the call stack, and so on back to the main program, if necessary. 
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After it is invoked, a handler might perform one of the following actions: 
¢ It handles the exception, thus allowing the program to continue execution. 


e¢ It resignals the exception. The operating system then searches for another 
handler down the call stack. 


e¢ It encounters a breakpoint or watchpoint, thereby suspending execution at 
the breakpoint or watchpoint. 


e It generates its own exception. In this case, the primary handler is invoked 
again. 


e It exits, thus terminating program execution. 


9.4.3.4 Final and Last-Chance Handlers 


These handlers are controlled by the debugger. They enable the debugger to 
ultimately regain control and display the DBG> prompt if no application-declared 
handler has handled an exception. Otherwise, the debugging session would 
terminate, and control would pass to the DCL command interpreter. 


The final handler is the last frame on the call stack and the first of these two 
handlers to be invoked. The following example illustrates what happens when 
an unhandled exception is propagated from an exception breakpoint to the final 
handler: | 


DBG> SET BREAK/EXCEPTION 
DBG> GO 


@SYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
break on exception preceding TEST\%LINE 13 

6: X := 3/Y; 
DBG> GO . 
sSYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=0000066C, PSL=03C00022 
DBG> 


In this example, the first INTDIV message is issued by the primary handler, and 
the second is issued by the final handler, which then displays the DBG> prompt. 


The last-chance handler is invoked only if the final handler cannot gain control 
because the call stack is corrupted. For example: 


DBG> DEPOSIT %FP = 10 
DBG> GO 


$SYSTEM-F-ACCVIO, access violation, reason mask=00, virtual address=0000000A, PC=0000319C, PSL=03C00000 
SDEBUG-E-LASTCHANCE, stack exception handlers lost, re-initializing stack 
DBG> 


The catchall handler, which is part of the VMS operating system, is invoked if the 
last-chance handler cannot gain control. The catchall handler produces a register 
dump. This should never occur if the debugger has control of your program. 


But it can occur if your program encounters an error when running without the 
debugger. 


If, during a debugging session, you observe a register dump and are returned to 
DCL level, submit an SPR to Digital. 
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9.4.4 Exception-Related Built-In Symbols 


When an exception is signaled, the debugger sets the following exception-related 
built-in symbols. 


Symbol Description 

%EXC_FACILITY Name of facility that issued the current exception 

%EXC_NAME Name of current exception 

%ADAEXC_NAME Ada exception name of current exception (for Ada programs only) 
%EXC_NUMBER Number of current exception 


%EXC_SEVERITY Severity code of current exception 


You can use these symbols as follows: 


¢ To obtain information about the fields of the VMS condition code of the 
current exception. 


¢ To qualify exception breakpoints (or tracepoints) so that they trigger only on 
certain kinds of exceptions. 


The following examples illustrate the use of some of these symbols. Note that the 
conditional expressions in the WHEN clauses are language specific: 

DBG> EVALUATE %EXC_NAME 

‘ACCVIO! 

DBG> SET TRACE/EXCEPTION WHEN (EXC_NAME = "ACCVIO") 

DBG> EVALUATE %EXC_FACILITY 

"SYSTEM! 

DBG> EVALUATE %EXC_NUMBER 

12 

DBG> EVALUATE/CONDITION VALUE %EXC_NUMBER 

SSYSTEM-F-ACCVIO, access violation, reason mask=01, virtual address=FFFFFF30, PC=00007552, PSL=03C00000 

DBG> SET BREAK/EXCEPTION WHEN (%EXC_NUMBER = 12) 

DBG> SET BREAK/EXCEPTION WHEN (%EXC_SEVERITY .NE. "I" .AND. SEXC_SEVERITY .NE. "S") 


9.5 Debugging Exit Handlers 


Exit handlers are procedures that are called whenever an image requests the 
$EXIT system service or runs to completion. A user program can declare one or 
more exit handlers. The debugger always declares its own exit handler. 


At program termination, the debugger exit handler executes after all application- 
declared exit handlers have executed. 


To debug an application-declared exit handler, proceed as follows: 
1. Set a breakpoint in that exit handler. 


2. Cause the exit handler to execute, by means of one of the following 
techniques: 


¢ Include in your program an instruction that invokes the exit handler 
(usually a call to $EXIT). 


¢ Allow your program to terminate. 


e Enter the EXIT command. (Note that the QUIT command does not 
execute any user declared exit handlers.) 


When the exit handler executes, the breakpoint is activated and control is 
then returned to the debugger, which prompts for commands. 


9-15 


Debugging Special Cases 
9.5 Debugging Exit Handlers 


The SHOW EXIT_HANDLERS command gives a display of the exit handlers 
that your program has declared. The exit handler routines are displayed in 

the order that they are called. A routine name is displayed symbolically, if 
possible. Otherwise its address is displayed. The debugger’s exit handlers are not 
displayed. For example: 


DBG> SHOW EXIT HANDLERS 

exit handler at STACKS\CLEANUP 
exit handler at BLIHANDLER\HANDLER1 
DBG> 


9.6 Debugging AST-Driven Programs 


A program can use asynchronous system traps (ASTs) either explicitly, or 
implicitly by calling VMS system services or RTL routines that call application- 
defined AST routines. Section 9.6.1 explains how to facilitate debugging by 
disabling and enabling the delivery of ASTs originating with your program. 
Section 9.6.2 explains how delivery of an AST affects a SHOW CALLS display. 


9.6.1 Disabling and Enabling the Delivery of ASTs 


Debugging AST-driven programs can be confusing because interrupts originating 
from the program being debugged can occur, but are not processed, while 

the debugger is running (processing commands, tracing execution, displaying 
information, and so on). 


By default, the delivery of ASTs is enabled while the program is running. The 
DISABLE AST command disables the delivery of ASTs while the program is 
running and causes any such potential interrupts to be queued. 


The delivery of ASTs is always disabled when the debugger is running. 


The ENABLE AST command reenables the delivery of ASTs, including any 
pending ASTs. The command SHOW AST indicates whether the delivery of ASTs 
is enabled or disabled. 


To control the delivery of ASTs during the execution of a routine called with 
the CALL command, use the /[NOJAST qualifiers. The command CALL/AST 
enables the delivery of ASTs in the called routine. The command CALL/NOAST 
disables the delivery of ASTs in the called routine. If you do not specify /AST or 
/NOAST with the CALL command, the delivery of ASTs is enabled unless you 
have previously entered the DISABLE AST command. 


9.6.2 Call Frames Associated with ASTs in SHOW CALLS Display 
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The delivery of an AST creates one or more special call frames that appear in a 
SHOW CALLS display. These call frames are not symbolized and might make 
the SHOW CALLS display confusing. The following example illustrates what you 
might see in a SHOW CALLS display when an AST routine is on the call stack. 


Assume that a program calls the system service $SETIMR to set a timer that 
expires at a specified interval and then execute an application-defined AST 
routine, TIMER_ROUT, in the program. 


The following command lines set a breakpoint on routine TIMER_ROUT, start 
execution which is then suspended on that routine, and display the sequence of 
active calls at the breakpoint: 
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DBG> SET BREAK TIMER ROUT 
DBG> GO *, 
break at routine MOD1\TIMER ROUT 
14: paar ee ae Be ~ 
DBG> SHOW CALLS 
module name routine name line 
*MOD1 TIMER ROUT 14 


DBG> 


rel PC abs PC 
00000002 00000405 
00000000 80009E5E 


The bottom line is the call frame associated with the system AST dispatcher. 

It shows the absolute PC value when the AST was delivered. Because the AST 
dispatcher is in system space (as indicated by the high absolute address), no 
symbolic information (module name, routine name, line number) is available. 

A SHOW CALLS display associated with the delivery of an AST might also 
show some debugger call frames (module name SHARE$DEBUG) and diagnostic 
messages related to condition handling by the debugger. You should ignore such 


messages and call frames. 
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Debugging Multiprocess Programs 





This chapter describes features of the debugger that are specific to multiprocess 
programs (programs that run in more than one process). The features enable you 
to display process information and control the execution of specific processes. Use 
these features in addition to those explained in other chapters. 


The first section gets you started with multiprocess debugging. The remaining 
sections provide additional information. 


Throughout the chapter it is assumed that all images discussed are "debuggable" 
images—that is, images that can be brought under control of the debugger. A 
debuggable image is one that was not linked with the /NOTRACEBACK qualifier. 
As explained in Chapter 5, you have full symbolic information when debugging an 
image only if its modules were compiled and linked with the /DEBUG qualifier. 


10.1 Getting Started 


This section gives an overview of the multiprocess debugging environment and 
explains the basic techniques used to debug a multiprocess program. Refer to 
subsequent sections for additional details. 


10.1.1 Establishing a Multiprocess Debugging Configuration 


Before invoking the debugger, enter the following command to establish a 
multiprocess configuration: 


$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 


This command establishes a multiprocess configuration for the VMS job hierarchy 
in which the command was entered. As a result, after a debugging session is 
started, any debuggable image running in the same job can be controlled from 
that one session. 


See Section 10.2.1 for more information about debugging configurations and 
process relationships. See Section 10.2.9 for system requirements related to 
multiprocess debugging. 


10.1.2 Invoking the Debugger 


This section explains the usual way of starting a multiprocess debugging session. 
See Section 10.2.4 for additional techniques for invoking the debugger (for 
example, using the Ctrl/Y-DEBUG sequence or the CONNECT command). 


You typically initiate the execution of a multiprocess program by running the 
main image in the main (master) process. After the main image is running in 
the main process, the program might spawn one or more subprocesses to run 
additional images by issuing a LIB$SPAWN run-time library call or a $CREPRC 
system service call. 


10-1 


Debugging Multiprocess Programs 
10.1 Getting Started 


If the main image is debuggable, the debugger is invoked when you run the 
image. For example: 


$ RUN MAIN PROG 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is FORTRAN, module set to MAIN PROG 
SDEBUG-I-NOTATMAIN, type GO to get to start of main program 
predefined trace on activation at routine MAIN PROG in %PROCESS NUMBER 1 
DBG 1> 


As with a one-process program, the debugger displays its banner and prompt just 


prior to the start of execution of the main image. However, note two differences: 
the "predefined trace on ... " message and the debugger prompt. 


In a multiprocess configuration, the debugger traces each new process that is 
brought under control. In this case, the debugger traces the first process, which 
runs the main image of the program. (ZPROCESS_NUMBER is a built-in symbol 
that identifies a process number, just as %LINE identifies a line number.) 


The significance of the prompt suffix (’_1’) is explained in the next section. 


10.1.3 Visible Process and Process-Specific Commands 


The previous example shows that the debugger prompt in a multiprocess 
debugging configuration is different from that found in the default configuration. 


In a multiprocess configuration, "dynamic prompt setting" is enabled by default 
(SET PROMPT/SUFFIX=PROCESS_NUMBER). Therefore, the prompt has a 
process-specific suffix that indicates the process number of the visible process. 
The debugger assigns a process number sequentially, starting with process 1, to 
each process that comes under the control of a given debugging session. 


‘The visible process is the process that is the default context for issuing process- 


specific commands. Process-specific commands are those that start execution 
(STEP, GO, and so on) and those used for looking up symbols, setting breakpoints, 
looking at the call stack and registers, and so on. Commands that are not process 
specific are those that do not depend on the mapping of memory but, rather, affect 
the entire debugging environment (for example, keypad mode and screen mode 
commands). 


Unless dynamic prompt setting is disabled (SET PROMPT/NOSUFFIX), the 
debugger prompt suffix always identifies the visible process (for example, DBG_ 
1>). The SET PROMPT command provides several options for tailoring the 
prompt-string prefix and suffix to your needs. 


10.1.4 Obtaining Information About Processes 
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Use the SHOW PROCESS command to obtain information about processes 

that are currently under control of your debugging session. By default, SHOW 
PROCESS displays one line of information about the visible process. The 
following example shows the kind of information displayed immediately after you 
invoke the debugger: 


DBG_1> SHOW PROCESS 


Number Name Hold State Current PC 
* 1 JONES activated MAIN_PROG\SLINE 2 
DBG 1> 
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A one-line SHOW PROCESS display provides the following information about 
each process specified: 


The process number assigned by the debugger. In this case, the process 
number is 1 because this is the first process known to the debugger. The 
asterisk in the leftmost column (*) marks the visible process. 


The VMS process name. In this case, the VMS process name is JONES. 


Whether the process has been put on hold with a SET PROCESS/HOLD 
command, as explained in Section 10.1.7.2. (This process has not been put on 
hold.) 


The current debugging state for that process. A process is in the "activated" 
state when it is first brought under debugger control (that is, before it has 
executed any part of the program under debugger control). Table 10-1 
summarizes the possible debugging states that can appear in the state 
column. 


The location (symbolized, if possible) where execution of the image is 
suspended in that process. In this case, the image has not started execution. 


Table 10-1 Debugging States 
State Description 


Activated The image and its process have just been brought under 


debugger control, either through a DCL RUN/DEBUG 
command, a debugger CONNECT command, a Ctrl/Y— 
DEBUG sequence, or by the program signaling SS$_ 
DEBUG while it was not under debugger control. 


Break! A breakpoint was triggered. 


Interrupted Execution was interrupted in that process, either because 


execution was suspended in another process, or because 
the user interrupted execution with the abort-key sequence 
(Ctrl/C, by default). 


Step?! A STEP command has completed. 
Terminated The image has terminated execution but the process is 


still under debugger control. Therefore, you can obtain 
information about the image and its process. 


Trace! A tracepoint was triggered. 
Unhandled exception An unhandled exception was encountered. 
Watch of A watchpoint was triggered. 


1 See the SHOW PROCESS command in the command dictionary for a list of additional states. 


The SHOW PROCESS/ALL command provides information about all processes 
that are currently under debugger control (in the case of the previous example, 
a SHOW PROCESS/ALL command would show only process 1). The SHOW 
PROCESS/FULL command provides additional details about processes. 


Returning to the previous example, if you now enter a STEP command followed 
by a SHOW PROCESS command, the state column in the SHOW PROCESS 
display indicates that execution is suspended at the completion of a step: 
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DBG 1> SHOW PROCESS 


Number Name Hold State Current PC 
* 1 JONES step MAIN PROG\S%LINE 3 
DBG_1> 


Similarly, if you were to set a breakpoint and enter a GO command, a SHOW 
PROCESS command entered at the prompt after the breakpoint has triggered 
would identify the state as "break". 


10.1.5 Bringing a Spawned Process Under Debugger Control 
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Continuing with the example from the last section, assume that you have entered 
a few more STEP commands and, in the middle of a step, MAIN_PROG spawns a 
process to run a debuggable image called TEST. 


Because DBG$PROCESS has the value MULTIPROCESS, the spawned process is 
now requesting to connect to the current debugging session, and the image TEST 
is suspended at the start of execution. 


While the spawned process is waiting to be connected, it is not yet known to the 
debugger and cannot be identified in a SHOW PROCESS/ALL display. You can 
bring the process under debugger control using either of the following methods: 


e Enter a command, such as STEP, that starts execution. 


e Enter the CONNECT command without specifying a parameter. The 
CONNECT command is preferable in cases when you do not want the 
program to execute further. 


The following example illustrates use of the CONNECT command: 


DBG 1> STEP 
stepped to MAIN PROG\SLINE 18 in PROCESS NUMBER 1 
18: LIBSSPAWN ("RUN/DEBUG TEST") 


DBG_1> STEP 
stepped to MAIN | PROG\SLINE 21 in %PROCESS NUMBER 1 
242 X= 7 


DBG_1> CONNECT 
predefined trace on activation at routine TEST in PROCESS NUMBER 2 
DBG 1> 


In this example, the second STEP command takes you past the LIB$SPAWN call 
that spawns the process. The CONNECT command brings the waiting process 
under debugger control. After entering the CONNECT command, you might 
need to wait a moment for the process to connect. The "predefined trace on... " 
message, as explained in Section 10.1.2, indicates that the debugger has taken 
control of a new process and identifies that process as process 2, the second 
process known to the debugger in this session. 


A SHOW PROCESS/ALL command, entered at this point, identifies the debugging 


. state for each process and the location at which execution is suspended: 
_ DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC. 

* 1 JONES step MAIN PROG\SLINE 21 
2 JONES 1 activated TEST\SLINE 1+2 

DBG_1> 


Note that the CONNECT command brings any processes that are waiting to be 
connected to the debugger under debugger control. If no processes are waiting, 
you can press Ctrl/C to abort the CONNECT command and display the debugger 
prompt. 
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10.1.6 Broadcasting Commands to Specified Processes 


By default, process-specific commands are executed in the context of the visible 
process. The DO command enables you to execute commands in the context of 
one or more processes that are currently under debugger control. This is also 
referred to as "broadcasting" commands to processes. 


Use the DO command without a qualifier to execute commands in the context of 
all of the processes. For example, the following command executes the SHOW 
CALLS command for all processes currently under debugger control (processes 1 
and 2, in this case): 


DBG_1> DO (SHOW CALLS) 
For SPROCESS NUMBER 1 


module name routine name line rel PC abs PC 

*MAIN_ PROG MAIN PROG 21 Q000001E 00000415 
For %PROCESS NUMBER 2 — 

module name routine name line rel PC abs PC 

TEST TEST 1+2 0000000B 0000040B 


As indicated in this example, the debugger identifies the process associated with 
any debugger output. 


Use the DO command with the /PROCESS= qualifier to execute commands in the 
context of specific processes. For example, the following command executes the 
SET MODULE START and EXAMINE X commands in the context of process 2: 


DBG 1> DO/PROCESS=(%PROC 2) (SET MODULE START; EXAMINE X) 


For more information about how to specify processes in debugger commands, see 
Section 10.2.2. 


10.1.7 Controlling Execution 


Program execution in a multiprocess debugging environment follows these 
conventions: 


¢ When you enter a command that starts program execution, such as STEP or 
GO, the command is executed in the context of the visible process. However, 
images in any other processes that have not been put on hold (with a SET 
PROCESS/HOLD command) are also allowed to execute. Similarly, if you use 
the DO command to broadcast a command to start execution in one or more 
processes, the command is executed in the context of each specified process 
that is not on hold, but images in any other processes that are not on hold are 
also allowed to execute. In all cases, a hold condition is ignored in the visible 
process. (See Section 10.1.7.2 for additional information about the behavior of 
processes on hold.) 


¢ After execution is started, the way in which it continues depends on whether 
the SET MODE [NOJINTERRUPT command was entered. By default (SET 
MODE INTERRUPT), execution continues until it is suspended in any 
process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 


These concepts are illustrated next by continuing with the example in 
Section 10.1.5 that illustrates the use of the CONNECT command. 


In that example, the "stepped to... " messages indicate that both commands 
are executed in the context of process 1, the visible process. The second 
STEP command spawns process 2. The SHOW PROCESS/ALL example of 
Section 10.1.5 indicates that execution in processes 1 and 2 is suspended at 
MAIN_PROG\ %LINE 21 and TEST\ “LINE 1+2, respectively. 
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At this point, entering another STEP command followed by SHOW PROCESS 
/ALL results in the following display: 


DBG_1> STEP 

stepped to MAIN PROG\%LINE 23 in %PROCESS NUMBER 1 

23% Y=15 

DBG_1> SHOW PROCESS/ALL 

Number Name Hold State Current PC 

x 1 JONES step MAIN PROG\%LINE 23 
2 JONES 1 interrupted TEST\SLINE 3+1 

DBG 1> 


The STEP command is executed in the context of process 1, the visible process. 
After the STEP command, execution in process 1 is suspended at MAIN_ 
PROG\ %LINE 28. However, the STEP command also causes execution to start 
in process 2. The completion of the STEP command in process 1 causes execution 
in process 2 to be interrupted at TEST\ ZLINE 3+1. 


Section 10.1.7.1 describes another mode of execution, which is provided by the 
SET MODE NOINTERRUPT command. 


10.1.7.1 Controlling Execution with SET MODE NOINTERRUPT 


The SET MODE NOINTERRUPT command allows execution to continue without 
interruption in other processes when it is suspended in some process. This is 
especially useful if, for example, you want to broadcast a STEP command to 
several processes with the DO command, then complete execution of the STEP 
command in all these processes. For example: 


DBG_1> SET MODE NOINTERRUPT 
DBG_1> DO (STEP) 


In this example, the DO command executes the STEP command in the context of 
all processes. The visible process and any other processes that are not on hold 
start execution. Because the SET MODE NOINTERRUPT command was entered, 
the prompt is displayed only after the STEP command has completed execution 
(or execution has been otherwise suspended at a breakpoint or watchpoint) in all 
processes that were executing. 


When SET MODE NOINTERRUPT is in effect, as long as execution continues in 
any process, the debugger does not prompt for input. In such cases, use Ctrl/C to 
interrupt all processes and display the prompt. 


10.1.7.2 Putting Specified Processes on Hold 


As indicated in the preceding sections, a command that starts execution is 
executed in the context of the visible process, but it also causes execution to start 
in other processes. If you want to inhibit execution in a process, put it on hold. 
For example, the following SET PROCESS/HOLD command puts process 2 on 
hold. The subsequent STEP command is executed in the context of process 1, the 
visible process. Execution also starts in any other processes that are not on hold, 
but not in process 2: 


DBG_1> SET PROCESS/HOLD %PROC 2 
DBG_1> STEP 


A SHOW PROCESS display indicates whether a process is on hold. For example: 
DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
x 1 JONES step MAIN PROG\%SLINE 24 
2 JONES 1 HOLD interrupted TEST\SLINE 3+1 
DBG 1> 
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To release a process from the hold condition, enter the SET PROCESS/NOHOLD 
command, and specify the process. 


Note that a hold condition is ignored in the visible process. Therefore, the SET 
PROCESS/HOLD/ALL command is a convenient way to confine execution to the 
visible process. In the following example, execution starts only in the visible 
process: 


DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> STEP 


This feature is useful if, for example, you want to use the CALL command to 
execute a dump routine that is not part of the execution stream of your program. 


The preceding discussions also apply if you use the DO command to broadcast 
a GO, STEP, or CALL command to several processes. The GO, STEP or CALL 
command is executed in the context of each specified process that is not on hold, 
and execution also starts in any other process that is not on hold. The following 
example illustrates the execution behavior when all processes are put on hold 
and commands are broadcast to all processes. Execution starts only in the visible 
process (process 1, in this example): 
DBG_1> SET PROCESS/HOLD/ALL 
DBG 1> DO (EXAMINE X; STEP) 
For @PROCESS NUMBER 1 

MAIN PROG\X: 78 
For PROCESS NUMBER 2 

TEST\X: 29 
stepped to MAIN PROG\%LINE 26 in SPROCESS NUMBER 1 
26: K=K+H+1 
DBG_1> 


10.1.8 Changing the Visible Process 


Use the SET PROCESS command (with the default /VISIBLE qualifier) to 
establish another process as the visible process. For example, the following 
command makes process 2 the visible process: 


DBG_1> SET PROCESS %PROC 2 
DBG_2> 


In this example, because dynamic prompt setting is enabled by default, the SET 
PROCESS command also has caused the prompt string suffix to change. It now 
indicates that process 2 is the visible process. All process-specific commands 
are now executed in the context of process 2. For example, a SHOW CALLS 
command would display the call stack for the image running in process 2. 


10.1.9 Dynamic Process Setting 


By default, "dynamic process setting" is enabled (SET PROCESS/DYNAMIC). 
As a result, whenever the debugger suspends program execution and displays 

its prompt, the process in which execution is suspended becomes the visible 
process automatically. Dynamic process setting occurs in the following situations: 
when a breakpoint or watchpoint is triggered, at an exception condition, on the 
completion of a STEP command, or when the last process performs an image exit. 


When dynamic process setting is disabled (NODYNAMIC), the visible process 
remains unchanged until you specify another process with the SET PROCESS 
/VISIBLE command. 
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Dynamic process setting is illustrated in the following example, which also 
illustrates dynamic prompt setting: 


DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 

x 1 JONES step MAIN PROG\SLINE 22 
2 JONES 1 interrupted TEST\SLINE 4 

DBG_1> DO/PROCESS=(%PROC 2) (SET BREAK %LINE 11) 


DBG_1> GO 


break at TEST\$LINE 11 in $PROCESS NUMBER 2 
DBG 2> SHOW PROCESS/ALL 


Number Name Hold State Current PC 

1 JONES interrupted MAIN PROG\%LINE 28 
* 2 JONES 1 break TEST\%LINE 11 
DBG 2> 


In this example, process 1 is initially the visible process, as indicated by the 
prompt and the SHOW PROCESS display. The DO command sets a breakpoint 
in the context of process 2. Execution is resumed with the GO command and is 
suspended at the breakpoint in process 2. Process 2 is now the visible process, as 
indicated by the prompt and the SHOW PROCESS display. 


If you have entered the SET MODE NOINTERRUPT command and then started 
execution in several processes with the DO command, the prompt is displayed 
only after execution has been suspended in all processes. In this case, the visible 
process remains unchanged, unless the last process performs an image exit (and 
thereby becomes the visible process). 


10.1.10 Monitoring the Termination of Images 


When the main image of a process runs to completion, the process goes into the 
"terminated" debugging state (not to be confused with process termination in the 
VMS sense). This condition is traced by default, as if you had entered the SET 
TRACE/TERMINATING command. 


When a process is in the terminated debugging state, it is still known to the 
debugger and appears in a SHOW PROCESS/ALL display. You can enter 
commands to examine variables, and so on. 


When the last image of the program exits, the debugger gains control and 
displays its prompt. 


10.1.11 Ending the Debugging Session 
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To end the entire debugging session, use the EXIT or QUIT command without 
specifying any parameters. 


EXIT executes any exit handlers that are declared in the program. QUIT does 
not. 


Thus, when you do not specify any parameters, the behavior of EXIT and QUIT 
is analogous to their behavior for the default debugging configuration. 
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10.1.12 Terminating Specified Processes 


To terminate specified processes without ending the debugging session, use 

the EXIT or QUIT command, specifying one or more process specifications as 
parameters. For example, the following command terminates the image running 
in process 2 and terminates the process: 


DBG_3> EXIT $PROC 2 
DBG_3> 


Subsequently, process 2 does not appear in a SHOW PROCESS display. See the 
command dictionary for complete details on the EXIT and QUIT commands. 
10.1.13 Interrupting Program Execution 


Pressing Ctrl/C (or the abort-key sequence established with the SET ABORT_ 
KEY command) interrupts execution in every process that is currently running an 
image. This is indicated as an "interrupted" state in a SHOW PROCESS display. 


As in the default configuration, you can also use Ctrl/C to abort a debugger 
command. 

10.2 Supplemental Information 
This section provides additional details or more advanced concepts and usages 
than those covered in Section 10.1. 

10.2.1 Debugging Configurations and Process Relationships 


You can invoke the debugger in either the default configuration or the 
multiprocess configuration to debug programs that run in either one or 
several processes, respectively. 


The debugging configuration depends on the current definition of the logical name 
DBG$PROCESS, as indicated in the following table. 


Definition of Logical Name 


DBG$PROCESS Resulting Debugging Configuration 

Undefined or DEFAULT Default (use this configuration with a program that 
runs in one process) 

MULTIPROCESS Multiprocess (use this configuration with a program 


that runs in several processes) 


Note that the debugging configuration does not depend on whether the program 
runs in one or several processes. Rather, the value of DBG$PROCESS determines 
whether debuggable images running in different processes can be controlled from 
the same debugging session. 


Before invoking the debugger, enter the DCL command SHOW LOGICAL 
DBG$PROCESS to determine the current definition of DBG$PROCESS and the 
resulting debugging configuration. 
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10.2.1.1 Establishing a Default Debugging Configuration 


To determine the current debugging configuration, use the SHOW LOGICAL 
DBG$PROCESS command. 


In the following example, the output of the command indicates that a default 
debugging configuration is in effect: 


$ SHOW LOGICAL DBGSPROCESS 

sSHOW-S-NOTRAN, no translation for logical name DBG$PROCESS 

If DBG$PROCESS has the value MULTIPROCESS, and you want to debug a 
program that runs in only one process, enter the following command: 

$ DEFINE DBGSPROCESS DEFAULT 


10.2.1.2 Establishing a Multiprocess Debugging Configuration 


The multiprocess debugging configuration enables you to interact with several 
processes from one debugging session. 


Use the following command to establish a multiprocess debugging configuration: 
$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 


As shown in this example, when defining DBG$PROCESS for a multiprocess 
configuration, use a job logical definition so that the definition applies to all 
processes in that job. An image can be connected to (and controlled by) an 
existing multiprocess debugging session only if the process running the image is 
in the same job as the process running the debugging session. 


In the typical multiprocess scenario, the program runs in one master parent 
process and several subprocesses. The debugger is invoked from the master 
process, then the program creates subprocesses during execution (a subprocess 


can also become the parent of another level of subprocesses). 


Another possible scenario is that the program runs in several peer processes. 
There is no master process. This configuration would result if you invoked the 
debugger by running one debuggable image and then used the SPAWN/NOWAIT 
command repeatedly to spawn other processes and run a debuggable image in 
each spawned process. 


10.2.1.3 Process Relationships When Debugging 
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The debugger consists of two parts: A relatively small kernel debugger 
image (DEBUG.EXE) and a larger main debugger image (DEBUGSHR.EXE) 
that contains most of the debugger code. This separation reduces potential 
interference between the debugger and the program being debugged. 


The separation also makes it possible to have two debugging configurations: 
a default configuration and a multiprocess configuration. Regardless of the 
configuration, the presence of a main debugger running in some process 
establishes a unique debugging session. 


When you invoke the debugger in the default configuration, the program runs in 
its process along with the kernel debugger, and a new subprocess is created to 
run the main debugger. A new main debugger (and, therefore, a new debugging 
session) is established every time you invoke the debugger. 


In the multiprocess configuration, the program being debugged runs in several 
processes. Each process that is running one or more images under debugger 
control is also running a local copy of the kernel debugger. The main debugger, 
running in a separate subprocess, communicates with the other processes through 
their kernel debuggers. | 
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Although all processes of a multiprocess configuration must be in the same 
job, they do not have to be related in a particular process/subprocess hierarchy. 
Moreover, the program images running in separate processes do not have to 
communicate with each other. 


See Section 10.2.9 for system requirements related to multiprocess debugging. 


10.2.2 Specifying Processes in Debugger Commands 


When specifying processes in debugger commands, you can use any of the forms 
listed in Table 10-2, except when specifying processes with the CONNECT 
command (see Section 10.2.4.2). 


The CONNECT command is used to bring a process that is not yet known to 

the debugger under debugger control. Therefore, when specifying a process with 
CONNECT, you can use only its VMS process name or VMS process identification 
number (PID). You cannot use its debugger-assigned process number or any of the 
process built-in symbols (for example, %NEXT_PROCESS) for the process. 


‘Table 10-2 Process Specifications 


Format Usage 

[%PROCESS_NAME] process-name The VMS process name, if that name 
contains no spaces or lowercase characters’. 

[%PROCESS_NAME] "process-name" The VMS process name, if that name 


contains spaces or lowercase characters. 
You can also use apostrophes (’ ) instead of 
quotation marks ("). 


%PROCESS_PID process_id The VMS process identification number | 
(PID, a hexadecimal number). 


%PROCESS_NUMBER process-number The number assigned to a process when 
(or %PROC process-number) it comes under debugger control. A new 
number is assigned sequentially, starting 
with 1, to each process. If a process 
is terminated with the EXIT or QUIT 
command, the number is not reused during 
the debugging session. Process numbers 
appear in a SHOW PROCESS display. 
Processes are ordered in a circular list 
so they can be indexed with the built- 
in symbols %PREVIOUS_PROCESS and 
%NEXT_PROCESS. 


process-group-name A symbol defined with the DEFINE 
/PROCESS_GROUP command to represent a 
group of processes. 


%NEXT_PROCESS The next process after the visible process in 
the debugger’s circular process list. 

%PREVIOUS_PROCESS The process previous to the visible process in 
the debugger’s circular process list. 

%VISIBLE_PROCESS The process whose stack, register set, and 


images are the current context for looking 
up symbols, register values, routine calls, 
breakpoints, and so on. 


1 The process name can include the wildcard character (* ). 
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You can omit the Z%PROCESS_NAME built-in symbol when entering commands. 
For example: 


DBG_2> SHOW PROCESS %PROC 2, JONES 3 
You can define a symbol to represent a group of processes (DEFINE/PROCESS_ 
GROUP). This enables you to enter commands in abbreviated form. For example: 


DBG_1> DEFINE/PROCESS GROUP SERVERS=FILE SERVER, NETWORK_SERVER 
DBG_1> SHOW PROCESS SERVERS 


Number Name Hold State Current PC 

us 1 FILE_SERVER step FS _PROG\SLINE 37 
2 NETWORK_SERVER break NET PROG\SLINE 24 

DBG_1> 


The built-in symbols %VISIBLE_PROCESS, %NEXT_PROCESS, and 
%PREVIOUS_PROCESS are useful in control structures based on the IF, 
WHILE, or REPEAT commands and in command procedures. 


10.2.3 Monitoring Process Activation and Termination 


By default, a tracepoint is triggered when a process comes under debugger 
control and when it performs an image exit. These predefined tracepoints are 
equivalent to those resulting from entering the SET TRACE/ACTIVATING and 
SET TRACE/TERMINATING commands, respectively. You can set breakpoints 
on these events by means of the SET BREAK/ACTIVATING and SET BREAK 
/TERMINATING commands. 


To cancel the predefined tracepoints, use the CANCEL TRACE/PREDEFINED 
command with the /ACTIVATING and /TERMINATING qualifiers. To cancel any 
user-defined activation and termination breakpoints, use the CANCEL BREAK 
command with the /ACTIVATING and /TERMINATING qualifiers (the /USER 
qualifier is assumed by default when canceling breakpoints or tracepoints). 


The debugger prompt is displayed when the first process comes under debugger 
control. This enables you to enter commands before the main image has started 
execution, as with a one-process program. 


Also, the debugger prompt is displayed when the last process performs an image 
exit. This enables you to enter commands after the program has completed 
execution, as with a one-process program. 


10.2.4 Interrupting the Execution of an Image to Connect It to the Debugger 


You can interrupt a debuggable image that is running without debugger control 
in a process and connect that process to the debugger. 


e To start a new debugging session, use the Ctrl/Y-DEBUG sequence from DCL 
level. 


e To interrupt an image and connect it to an existing debugging session, use 
the CONNECT command. 


10.2.4.1 Using the Ctri/Y-DEBUG Sequence to Invoke the Debugger 
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You use the Ctrl/Y-DEBUG sequence with the multiprocess debugging 
configuration exactly as with the default configuration. That is, run the image 
from DCL level with the RUN/NODEBUG command, then press Ctrl/Y to 
interrupt the image. The DEBUG command causes the debugger to be invoked. 
(See Section 3.1.2.) 
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The following example shows how you might start a new debugging session: 


$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 
$ RUN/NODEBUG PROG2 


civ 
Interrupt 
$ DEBUG 


VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in PROCESS NUMBER 1 
DBG 1> 


In this example, the DEFINE/JOB command establishes a multiprocess 
debugging configuration. The RUN/NODEBUG command starts the execution of 
image PROG2 without debugger control. The Ctrl/Y-DEBUG sequence interrupts 
execution and invokes the debugger. 


The VAX DEBUG banner indicates that a new debugging session has been 
started. The process-specific prompt (DBG_1>) indicates that this is a 
multiprocess configuration and that execution is suspended in process 1, which is 
running image PROG2. 


The activation tracepoint identifies the location at which execution was 
interrupted (and at which the debugger took control of the process). You can 
also use the SHOW CALLS command to display the call stack at that location. 


After the debugger has been invoked, you can use the CONNECT command to 
bring other processes under debugger control. In the previous example, you could 
use the CONNECT command to bring processes under debugger control that were 
created by PROG2 before you interrupted its execution (see Section 10.2.4.2). 


When using the Ctrl/Y-DEBUG sequence, if a multiprocess debugging session 
already exists in the same job as the image that is interrupted, the image 
connects to that session. In this case, because a new session is not started, 

the VAX DEBUG banner is not displayed when the debugger takes control. This 
situation could occur if, for example, you entered a SPAWN/NOWAIT command 
from the session, started execution with a RUN/NODEBUG command, and then 
entered a Ctrl/Y-DEBUG sequence. 


10.2.4.2 Using the CONNECT Command to Interrupt an Image 


The CONNECT command, used without a parameter, was introduced in 
Section 10.1.5. When used with a parameter, the CONNECT command enables 
you to interrupt a debuggable image that is running without debugger control 
and bring it under control of your current debugging session. 


The image might have been activated as follows: 


¢ Your program issued a LIB$SPAWN run-time library call or a $CREPRC 
system service call to spawn a process and run an image without debugger 
control 


¢ You started execution with a RUN/NODEBUG command entered at DCL level 


In the following example, the CONNECT command causes the image running 
in process JONES_3 to be interrupted and to come under control of the current 
debugging session. Process JONES_3 must be in the same job as the session. 


DBG_1> CONNECT JONES 3 


10-13 


Debugging Multiprocess Programs 
10.2 Supplemental Information 


Note that a process is not identified by a debugger process number until it is 
connected to a debugging session. Therefore, when specifying a process with the 
CONNECT command, you can use only its VMS process name or VMS process 
identification number (PID). 


The effect of the CONNECT command is equivalent to attaching to a process from 
a debugging session and then entering the sequence Ctrl/Y-DEBUG to interrupt 


' the running image and invoke the debugger. However, the CONNECT command 


is easier to enter and also enables you to interrupt a process to which you cannot 
attach. 


10.2.5 Screen Mode Features for Multiprocess Debugging 


Screen mode displays, whether predefined or user defined, are associated with 
the visible process by default. For example, SRC shows the source code where 
execution is suspended in the visible process, OUT shows the output of commands 
executed in the context of the visible process, and so on. 


By using the /PROCESS qualifier with the DISPLAY command you can create 
process-specific displays or make existing displays process specific, respectively. 
The contents of a process-specific display are generated and modified in the 
context of that process. You can make any display process specific except for the 
PROMPT display. For example, the following command creates the automatically 
updated source display SRC_8, which shows the source code where execution is 
suspended in process 3: 


DBG_2> DISPLAY/PROCESS=(%PROC 3) SRC_3 AT RS23 SOURCE (EXAM/SOURCE .%SOURCE_SCOPE\%PC) 
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You assign attributes to process-specific displays as for displays that are not 
process specific. For example, the following command makes display SRC_3 the 
current scrolling and source display—that is, the output of SCROLL, TYPE, and 
EXAMINE/SOURCE commands are then directed at SRC_3: 


DBG_2> SELECT/SCROLL/SOURCE SRC_3 


If you enter a DISPLAY/PROCESS command without specifying a process, the 
specified display is then specific to the process that was the visible process when 
you entered the command. For example, the following command makes OUT_X 
specific to process 2: 


DBG_2> DISPLAY/PROCESS OUT_X 


The /SUFFIX qualifier appends a process identifying suffix that denotes the 
visible process to a display name. This qualifier can be used directly after a 
display name in any command that specifies a display (for example, DISPLAY, 
EXTRACT, SAVE). It is especially useful within command procedures in 
conjunction with display definitions or key definitions that are bound to display 
definitions. 


In a multiprocess configuration, the predefined tracepoint on process activation 
automatically creates a new source display and a new instruction display for each 
new process that comes under debugger control. The displays have the names 
SRC_n and INST_n, respectively, where n is the process number. These displays 
are initially marked as removed. They are automatically deleted on process 
termination. 


Several predefined keypad key sequences enable you to configure your screen with 
the process-specific source and instruction displays that are created automatically 
when a process is activated. Key sequences that are specific to multiprocess 
programs are as follows: PF1—-9, PF4-9, PF4—7, PF4~3, PF4—1. See Section B.5 
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for the general effect of these sequences. Use the SHOW KEY command to 
determine the exact commands. 


10.2.6 Setting Watchpoints in Global Sections 


You can set watchpoints in global sections. A global section is a region of memory 
that is shared among all processes of a multiprocess program. A watchpoint that 
is set on a location in a global section (a global section watchpoint) triggers when 
any process modifies the contents of that location. 


When setting watchpoints on arrays or records, note that performance is 
improved if you specify individual elements rather than the entire structure 
with the SET WATCH command. 


If you set a watchpoint on a location that is not yet mapped to a global section, 
the watchpoint is treated as a conventional static watchpoint. For example: 


DBG _1> SET WATCH ARR(1) 
DBG 1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 


When ARR is subsequently mapped to a global section, the watchpoint is 
automatically treated as a global section watchpoint and an informational 
message is issued. For example: 


DBG_1> GO 
SDEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has 
been remapped to a global section 
predefined trace on activation at routine PPL3 in PROCESS NUMBER 2 
predefined trace on activation at routine PPL3 in PROCESS NUMBER 3 
watch of PPL3\ARR(1) at PPL3\%LINE 93 in %PROCESS NUMBER 2 
93: ARR(1) = INDEX 

old value: 0 

new value: 1 
break at PPL3\%LINE 94 in PROCESS NUMBER 2 

94: ARR(I) = I 


' After the watched location is mapped to a global section, the watchpoint is visible 
from each process. For example: 
DBG 2> DO (SHOW WATCH) 
For tPROCESS NUMBER 1 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For tPROCESS NUMBER 2 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For %PROCESS NUMBER 3 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 


10.2.7 Using Multiprocess Commands with the Default Configuration 


All commands, qualifiers, and built-in symbols that are provided for multiprocess 
debugging are also understood in the default debugging configuration and have 
analogous behaviors (where applicable). For example: 


¢ The EXIT command without a parameter ends a debugging session in both 
configurations. 


¢ ADO command without the /PROCESS qualifier executes the commands 
specified in all processes. 


¢ In the default configuration, the visible process is the process that runs the 
entire program. It is identified as process 1 in a SHOW PROCESS display. 


e Process-specific built-in symbols, such as 2PROCESS_NUMBER and 
%VISIBLE_PROCESS, are interpreted correctly in the default configuration. 
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This compatibility enables you to use command procedures designed for 
multiprocess debugging when debugging programs that run in only one process. 


10.2.8 Advanced Concepts and Possible Errors 


The debugging configuration (default or multiprocess) is controlled entirely by 
the definition of DBG$PROCESS. If some of the processes in a job have different 
definitions of DBG$PROCESS, the resulting debugging configuration can be very 
confusing. 


The value of DBG$PROCESS is checked when the kernel debugger is first 
invoked. 
Consider the following scenario: 


$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 
$ RUN TEST 


VAX DEBUG Version 5.5 


DBG_1> SET BREAK/ACTIVATING;GO 
break at program activation in %PROCESS NUMBER 2 
DBG_2> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
1 SMITH interrupted TEST\SLINE 50 
* 2 SMITH 1 activated SUB1\$LINE 71 


DBG_2> SPAWN DEFINE DBGSPROCESS DEFAULT ! Establish a default configuration 
DBG 2> SET BREAK %LINE 100;GO ! Assume that TEST creates a new process 


VAX DEBUG Version 5.5 


break at sLINE 100 in %PROCESS NUMBER 2 
DBG> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
. 3 SMITH 2 activated MYPROG\%SLINE 10 
DBG_2> SHOW PROCESS/ALL 
Number Name Hold State Current PC 
1 SMITH interrupted TEST\SLINE 50 
x 2 SMITH 1 break SUB1\SLINE 100 
DBG> ~ 


Because of the reassigment of DBG$PROCESS, there are two different main 
debuggers (two debugging sessions) in the job. Both debuggers use the same 
terminal for input and output. Therefore, the prompts and output lines from the 
two sessions are intermixed on the screen. (The effect is similar to what you see 
if you enter a DCL SPAWN/NOWAIT command, in that two processes are sharing 
the terminal.) 


Generally, this mixed default and multiprocess configuration is not desirable. 
However, although potentially confusing, the configuration can be useful if 

you need to debug an experimental copy of a program without disturbing your 
primary debugging session, which has several processes connected to it. In such 
cases, use the SPAWN and ATTACH commands to control the activity of the 
subprocesses. 


10.2.9 System Requirements for Multiprocess Debugging 
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Several users debugging multiprocess programs can place a load on a system. 
This section describes the resources used by the debugger, so that you or your 
system manager can tune your system for this activity. 


Note that the discussion covers only the resources used by the debugger. You 
might have to tune your system to support the multiprocess programs themselves. 
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10.2.9.1 User Quotas 


Each user needs a PRCLM quota sufficient to create an additional subprocess for 
the debugger, beyond the number of processes needed by the program. 


BYTLM, ENQLM, FILLM, and PGFLQUOTA are pooled quotas. They may need 
to be increased to account for the debugger subprocess as follows: 


* Each user’s ENQLM quota should be increased by at least the number of 
processes being debugged. 


e¢ Each user’s PGFLQUOTA might need to be increased. If a user has an 
insufficient P@FLQUOTA, the debugger might fail to activate or cause 
"virtual memory exceeded" errors during execution. 


¢ Each user’s BYTLM and FILLM quotas might need to be increased. The 
debugger requires BYTLM and FILLM quotas sufficient to open each image 
file being debugged, the corresponding source files, and the debugger input, 
- output, and log files. The debugger command SET MAX _SOURCE_FILES 
can be used to limit the number of source files kept open by the debugger at 
any one time. 


10.2.9.2 System Resources 
The kernel and main debugger communicate through global sections. The main 
debugger communicates with up to 8 kernel debuggers through a 65-page global 
section. Therefore, the SYSGEN global-page and global-section parameters 
(GBLPAGES and GBLSECTIONS, respectively) might need to be increased. For 
example, if 10 users are using the debugger simultaneously, 10 global sections 
using a total of 650 global pages are required by the debugger. 
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Debugging Vectorized Programs 


This chapter describes features of the debugger that are specific to vectorized 
programs (programs that use VAX vector instructions). Use these features in 
addition to those explained in other chapters. 


The information in this chapter enables you to perform the following tasks: 


e 


e 


Display information about the availability and use of the vector processor on 
your system 


Control and monitor the execution of vector instructions with breakpoints, 
watchpoints, and so on 


Examine and deposit into the vector control registers (7VCR, %VLR, and 
%VMR) and the vector registers (%V0 to %V15) 


Examine and deposit vector instructions and their operands 


Perform masked operations when examining vector registers or vector 
instructions to display only certain register elements or override the masking 
associated with a vector instruction 


When using the EXAMINE command, specify composite address expressions 
of a complex form that might be appropriate for a vectorized program 


Display the decoded results of vector floating-point exceptions 
Control synchronization between the scalar and vector processors 


Save and restore the current vector state when using the CALL command to 
execute a routine that might affect the vector state 


Display vector register data using a screen-mode display 


For additional information that is specific to a vectorized high-level language 
program, see the associated language documentation. For complete information 
about vector instructions and vector registers, see the VAX MACRO and 
Instruction Set Reference Manual. 


Notes 


1. Compilers do not generate symbol-table data to associate vector 
registers with symbols declared in the program. Therefore, no 
symbolization is available for vector registers during a debugging 
session. Also, you can access a vector register only in scope 0 (the 
scope of the routine at the top of the call stack). 
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2. The examples in this chapter show how to access elements of a 
vector register using array syntax (for example, EXAMINE %V1(87)). 
This syntax is not supported for BLISS. In BLISS, use the SET 
LANGUAGE command to set the language temporarily to some other 
language, such as FORTRAN, then use the array syntax for that 
language. 


11.1 Obtaining Information About the Vector Processor 


The SHOW PROCESS/FULL command provides some information about the 
availability and use of the vector processor on your system. For example: 


DBG> SHOW PROCESS/FULL 


Vector capable: Yes 


Vector consumer: Yes Vector CPU time: 0 00:03:17.18 
Fast Vector context switches: 0 Slow Vector context switches: 0 
DBG> 


The Vector Capable field can have the following entries: 


Vector-Capable Entry Description 


Yes The VAX system has a vector processor, and it is available to the 
process that is running the program. 


No (protected) The VAX system has a vector processor, but the process running 
the program is denied access to the processor. 


VVIEF The VAX system does not have a vector processor. It is running 
the VAX Vector Instruction Emulation Facility (VVIEF). The 
VVIEF is available to the process that is running the program. 


No The VAX system does not have an active vector processor, and 
the VVIEF is not loaded on the system. 


11.2 Controlling and Monitoring the Execution of Vector 
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Instructions 


The following sections explain how to perform the following tasks: 


¢ Execute the program to (step to) either the next vector instruction or any one 
of a set of specified vector instructions. 


¢ Set breakpoints and tracepoints that trigger either on any vector instruction 
or on any one of a set of specified vector instructions. 


¢ Set watchpoints to monitor changes in vector registers. 
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11.2.1 Executing the Program to the Next Vector Instruction 
To execute the program to the next vector instruction encountered in the program, 
enter the STEP/VECTOR_INSTRUCTION command. 


You can also execute the program to the next vector instruction whose opcode is 
in a list of opcodes by using the command STEP/INSTRUCTION=(opcode/, ... /). 
For example: 


DBG> STEP/INSTRUCTION= (VLDL, VSTL, MOVL) 


The SET STEP command enables you to change the default unit of execution of 
the STEP command: 


¢ Enter the SET STEP VECTOR_INSTRUCTION command to make the STEP 
command execute the program to the next vector instruction by default. 


¢ Enter the SET STEP INSTRUCTION=(opcode/, ... /) command to make the 
STEP command execute the program to the next instruction that is in the list 
of opcodes (including a vector instruction) by default. 


11.2.2 Setting Breakpoints and Tracepoints on Vector Instructions 


To set a breakpoint (or a tracepoint) that triggers whenever a vector instruction 
is encountered in the program, enter the SET BREAK/VECTOR_INSTRUCTION 
(or SET TRACE/VECTOR_INSTRUCTION) command. 


To cancel such breakpoints or tracepoints, enter the command CANCEL BREAK 
/VECTOR_INSTRUCTION or CANCEL TRACE/VECTOR_INSTRUCTION. 


You can also set breakpoints and tracepoints on one or more specific vector 
instructions by using the /INSTRUCTION=(opcode/, ... /) qualifier with the SET 
BREAK and SET TRACE commands. For example: 


DBG> SET BREAK/INSTRUCTION=(VVADDL, VVLEQL) 


To cancel such breakpoints and tracepoints, enter the CANCEL BREAK 
AINSTRUCTION or CANCEL TRACE/INSTRUCTION command. 


11.2.3 Setting Watchpoints on Vector Registers 


You can set watchpoints on the vector registers (VO to V15) and on the vector 
control registers (VCR, VLR, and VMR). Section 11.3.1 identifies these registers 
and their built-in debugger symbols. 


These watchpoints are treated like static watchpoints in that, once set, the 

watchpoint is active until you cancel it explicitly. 

In the following example, a watchpoint is set on register VCR: 

DBG> SET WATCH %VCR 

In the case of VMR and VO to V15, you can set a watchpoint either on the 

register aggregate (that is, on all elements of the register), on an individual 


register element, or on a range of elements (a slice). Use the same technique that 
you use to set a watchpoint on an array variable. (See Section 3.6.) 


For example, the following command sets a watchpoint that triggers if any 
element of register V5 changes: 


DBG> SET WATCH %V5 
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The following command sets a watchpoint that ‘niggers if element 37 of V2 
changes (FORTRAN array syntax): 


DBG> SET WATCH %V2 (37) 


The following command sets a watchpoint that triggers if any element of V2 in 
the range from element 5 to 18 changes: 


DBG> SET WATCH %V2 (5:13) 


11.3 Examining and Depositing into Vector Registers 


The following sections explain how to examine and deposit into the vector control 
registers (VCR, VLR, and VMR) and the vector registers (VO to V15). 


11.3.1 Specifying the Vector Registers and Vector Control Registers 


The VAX architecture provides 16 vector registers (VO to V15) and 3 vector 
control registers (VCR, VLR, VMR). When referencing any of these registers 
in a debugger command, use the following built-in symbols (the register name 
preceded by a percent sign (%)). 


Symbol Description 

%VO... MV1B Vector registers (VO ... V15) 
%VCR Vector count register (VCR) 
%VLR Vector length register (VLR) 
%VMR Vector mask register (VMR) 


As with all debugger register symbols, you can omit the percent sign (%) prefix if 
your program has not declared a symbol with the same name. 


11.3.2 Examining and Depositing into the Vector Count Register (VCR) 


The vector count register (VCR) specifies the length of the offset vector generated 
by the IOTA instruction. 


The value of VCR is an integer from 0 to 64. By default, the debugger treats VCR 
as a longword integer. Although you can deposit values greater than 64 into VCR, 
the debugger issues a diagnostic message that the value is out of bounds in such 
cases. 


The following command sequence shows how to manipulate the value of VCR: 


DBG> EXAMINE %VCR 
O\SVCR: 8 

DBG> DEPOSIT $VCR = 4 
DBG> EXAMINE %VCR 
O\SVCR: 4 

DBG> 


11.3.3 Examining and Depositing into the Vector Length Register (VLR) 
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The vector length register (VLR) limits the highest element of a vector register 
that is processed by a vector instruction. The value of VLR is an integer from 0 
to 64. This value specifies the number of register elements that are processed, 
starting with element 0. 


In the context of a debugging session, the current value of VLR limits the highest 
element of a vector register that yours can access with an EXAMINE or DEPOSIT 
debugger command. 
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The following command sequence shows how to manipulate the value of VLR to 
examine different numbers of elements of the vector register V1: 


DBG> EXAMINE %VLR 


O\SVLR: 4 

DBG> EXAMINE $V1 

O\3V1 
(0): 12 
(1): 3 
(2): 138 


(3): 51 
DBG> DEPOSIT %VLR = 3 
DBG> EXAMINE 3VLR 


O\SVLR: 3 
DBG> EXAMINE %V1 
0\$V1 
(0): 12 
(1): 3 
(2): 138 
DBG> 


You cannot access a register element outside the range from 0 to VLR—1. In the 
following example, the EXAMINE command specifies element 7 of register V1, 
which is out of bounds (FORTRAN array syntax): 

DBG> EXAMINE %VLR 

O\SVLR: 3 

DBG> EXAMINE %V1(7) 

SDEBUG-E-VECTSUBRNG, vector register subscript out of bounds, 


bounds are 0..2 
DBG> 


By default, the debugger treats VLR as a longword integer. Although you can 
deposit values greater than 64 into VLR, the debugger issues a diagnostic 
message that the value is out of bounds in such cases. 


11.3.4 Examining and Depositing into the Vector Mask Register (VMR) 


The vector mask register (VMR) specifies a mask (a bit pattern) that a vector 
instruction uses in order to operate on only certain elements of a vector register 
operand. A masked vector instruction cannot operate on an element of a vector 
register that is masked by VMR. 


VMR has 64 bits (1 quadword), numbered 0 to 68. Each bit corresponds to an 
element of a vector register. The value of a particular bit (0 or 1) determines 
whether the corresponding register element is operated on during a masked 
operation. 


Masked operations are explained in Section 11.4.1 and Section 11.5. This section 
describes only how to display and change the value of VMR. 


To examine one or more specific elements (bits) of VMR, use the same technique 
that you use to examine an array variable. (See Section 4.2.3.) 


For example, the output of the following command shows that bit 5 of VMR is set 
(FORTRAN array syntax): 


DBG> EXAMINE %VMR(5) 
O\SVMR (5) : 1 
DBG> 
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The following command displays the values of bits 4 to 6 of VMR. Bits 4 and 5 
are set, and bit 6 is clear: 


DBG> EXAMINE %VMR (4:6) 


0\SVMR 
(4): 1 
(5): al 
(6): 0 
DBG> 


By default, when you examine VMR without specifying subscripts, the debugger 
displays the value of the register as a quadword integer in hexadecimal format, 
to reduce the size of the output display. For example: 
DBG> EXAMINE %VMR 
O\SVMR 

(0): OFFFFFFE FFFFFFFF 
DBG> 


By specifying the EXAMINE/BIN %VMR or EXAMINE %VMR(0:63) command, 
you can display the value of each bit of VMR in a 64-row array format. 


As with an array variable, you can deposit a value into one bit of VMR at a time. 


- For example: 


DBG> EXAMINE %VMR (37) 
O\SVMR (37) : 1 

DBG> DEPOSIT %VMR(37) = 0 
DBG> EXAMINE %VMR (37) 
O\SVMR (37) : 0 

DBG> 


You can also deposit a quadword integer value into the entire aggregate by using 
the DEPOSIT/QUADWORD command. For example: 


DBG> DEPOSIT/QUADWORD %VMR = %HEX OFFFFF 
DBG> EXAMINE %VMR 
O\SVMR 
(0): 00000000 OOOFFFFF 
DBG> 


When specifying an element of VMR in a language expression, remember that 
VMR is an array of bits. You might have to temporarily set the language to one 
that allows bit operations, such as C or BLISS. For example: 

DBG> SET LANGUAGE C 


DBG> DEFINE/VALUE K = 0 
DBG> FOR I=0 TO 63 DO (IF %VMR[I] == 1 THEN (DEF/VAL K = K + 1)) 


11.3.5 Examining and Depositing into the Vector Registers (VO to V15) 
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There are 16 vector registers, designated VO to V15. Each of the vector registers 
has 64 elements, numbered 0 to 63, and each element has 64 bits (one quadword). 


To examine one or more elements of a vector register, use the same technique 
that you use to examine an array variable. (See Section 4.2.3.) The examples in 
this section use FORTRAN array syntax: 


DBG> EXAMINE %V3 ‘Examine all elements of V3 
DBG> EXAMINE $V3(27) 'Examine element 27 of V3 
DBG> EXAMINE %V3 (3:14) 'Examine elements 3 to 14 of V3 


DBG> EXAMINE $V0(2),%V3(1:4) ‘Examine element 2 of VO and 
felements 1 to 4 of V3 
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The values of register elements are displayed in an indexed format similar to that 
used for an array variable. For example, the following command displays the 
values of elements 1 to 3 of register V1: 


DBG> EXAMINE %V1 (1:3) 


O\SV1 
(1): 3 
(2): 138 
(3): 51 
DBG> 


Note that you cannot examine a range of vector registers. For example, the 
following commands are invalid: 


DBG> EXAMINE %V0:%V3 
DBG> EXAMINE %V2(7) :%V3(12) 


As with an array variable, you can deposit a value into only one element of 
a vector register at a time. For example, the following command deposits the 
integer value 8531 into element 9 of VO: 


DBG> DEPOSIT %V0(9) = 8531 


The current value of the vector length register (VLR) limits the highest register 
element that you can examine or deposit into. (See Section 11.3.3.) Therefore, the 
following commands are equivalent: 


DBG> EXAMINE %V1 
DBG> EXAMINE %V1(0:%VLR-1) 


The expression 0:%VLR-1 specifies the range of register elements that are 
denoted by the current value of VLR. 


By default, the debugger treats each element of a vector register as a longword 
integer and displays the value in the current radix. For example: 

DBG> EXAMINE %V3(27) 

0\$V3 (27): 5983 

DBG> DEPOSIT %V3(27) = 3625 

DBG> EXAMINE %V3(27) 

O\%V3 (27): 3625 

DBG> 


However, note that a register value that is examined in the context of a vector 


instruction (that is, as an instruction operand) is displayed in the data type that 
is appropriate for the instruction. (See Section 11.4.1.) 


To display the full (quadword) value of an element of a vector register as a 
quadword integer, use the EXAMINE/QUADWORD command. Similarly, to 
deposit a quadword integer value into a register element, use the command 
DEPOSIT/QUADWORD. 


You can also use any of the other type qualifiers associated with the EXAMINE 
and DEPOSIT commands (for example, /FLOAT) to override the default type. For 
example: 


DBG> EXAMINE %V5 (2) 
0 


O\SV5(2): 

DBG> EXAMINE/D FLOAT %V5 (2) 

O\%V5 (2): 0.0000000000000000 
DBG> 
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You can use register symbols in language expressions, subject to the restrictions 
on using aggregate data structures in language expressions. (See Section 4.1.5.1.) 
For example, the following expression is valid (FORTRAN syntax): 


DBG> EVALUATE %V0(4) .EQ. %V1(4) 


However, the following expression is not valid because more than one register 
element is specified: 


DBG> EVALUATE %V0 .EQ. $%V1 


11.4 Examining and Depositing Vector Instructions 
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The techniques for manipulating vector instructions include all of those used for 
scalar instructions (described in Section 4.3) and additional techniques specific to 
vector instructions: 


e You can use a screen-mode instruction display to present the scalar and 
vector instructions decoded from the instruction stream of your program. 


¢ You can execute your program at the vector instruction level by using 
commands such as the following: 


STEP/VECTOR_INSTRUCTION 
STEP/INSTRUCTION=(opcode/, .. . /) 

SET STEP VECTOR_INSTRUCTION 

SET STEP INSTRUCTION=(opcodef, . . . /) 
SET BREAK/VECTOR_INSTRUCTION 

SET BREAK/AINSTRUCTION=(opcodef/, .. . J) 


¢ You can use the EXAMINE/OPERANDS command to display the instruction 
at the current PC value, including any operand information contained in 
vector registers. In addition, the qualifiers /TMASK and /FMASK enable 
you to simulate the effect of the vector mask register (VMR) or override any 
masking associated with the examined instruction so that you can hide or 
display specific register elements. 


¢ You can deposit a vector instruction at a particular memory address in your 
program. 


Whether you are examining or depositing vector instructions, the debugger 
correctly processes the vector instruction qualifiers according to the instructions 
to which they apply. The following table summarizes the functions of these 
qualifiers. See the VAX MACRO and Instruction Set Reference Manual for 
complete information about their use. 


Instruction 

Qualifier Description 

/U Enable floating underflow (vector floating-point instructions) 

IV Enable integer overflow (vector integer instructions) 

/M Modify intent (VLDx and VGATH«x instructions) 

/0 Perform masked operations only on elements for which the VMR bit is 0 
/1 Perform masked operations only on elements for which the VMR bit is 1 
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11.4.1 Examining Vector Instructions and Their Operands 


When you examine a program location that contains a vector instruction, the 
debugger decodes that instruction and translates it and its operands into 

their VAX MACRO assembler form, with the following restrictions. (See the 
VAX MACRO and Instruction Set Reference Manual for details about instruction 
opcodes. ) 


¢ Ifthe vector control word is not encoded using either immediate or short- 
literal mode, the debugger cannot translate the opcode and, therefore, 
displays the instruction and its operands in their VAX vector architectural 
form rather than their VAX MACRO assembler form. 


e Ifthe VAX opcode is VSMERGEx, the debugger displays the instruction 
mnemonic as VSMERGE rather than VSMERGEF, VSMERGED, or 
VSMERGEG. In this case, a literal src.rg operand is displayed as a quadword 
integer in the current radix. 


The command EXAMINE/OPERANDS .%PC enables you to display the 
instruction at the current PC value and its operands. (See Section 4.3.1.) When 
you examine a vector instruction with this command, the values of any vector 
register operands are displayed as for an array variable. For example (FORTRAN 
array syntax): 
DBG> EXAMINE/OPERANDS .%PC 
PROGSMAIN\%LINE 81+19: VSTL VO, W*-572 (FP) ,S*#4 
VO contains: 

O\SVO(0): 137445504 

O\SVO(1): 137445504 

O\SV0(2): 137445504 


W*-572 (FP) 2145991456 contains 2 
DBG> 


As with scalar instructions, operand values are displayed in the data type that is 
appropriate for the examined instruction. 


When you use the EXAMINE/OPERANDS command, the display of register 
elements depends on the following factors: 


e The current value of VLR. The highest element of a vector register that is 
operated on (and, therefore, displayed) is limited by the value of VLR. 


¢ Whether the examined instruction is performing a masked operation. In 
an unmasked operation, all register elements (up to VLR—1) are displayed. 
A masked operation is indicated by the presence of the /1 or /0 instruction 
qualifier. For example: 


VVADDF/1 V0,V1,V2 
In a masked operation, only the elements that correspond to the set or clear 


bits of VMR are operated on (depending on whether the instruction qualifier 
is /1 or /0, respectively). 


These concepts are illustrated in the following two examples, which show an 
unmasked and a masked register-to-register operation, respectively. 


In the next example, the examined instruction, VVADDF, is performing an 
unmasked operation so that the current value of VMR is irrelevant. All elements 
from 0 to 5 are displayed: 
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DBG> EXAMINE %VLR 


O\SVLR: 6 
DBG> EXAMINE %VMR(0:5) 
0\SVMR 
(0): 1 
(1): 0 
(2) 1 
(3): 0 
(4): 1 
(57% 0 
DBG> EXAMINE/OPERANDS .%PC 
PROGSMAIN\%LINE 12: VVADDF V0,V1,V2 
VO contains: 
O\SV0(0): 7.0000000 
O\8VO(1): 7.0000000 
O\%V0(5): 7.0000000 
V1 contains: 
O\%V1(0): 4.0000000 
O\SV1(1): 4.0000000 
O\$V1(5): 4.0000000 


V2 contains: 
0\%V2(0): 5.0000000 
O\$V2 (1): 0000000 


wi 


0\8V2 (5) : 


an 


- 0000000 

DBG> 

In the next example, the same VVADDF instruction is performing a masked 
operation. The instruction qualifier /1 specifies that elements that match the set 
bits (bit value 1) in VMR are operated on: 


DBG> EXAMINE %VLR 


O\SVLR: 6 
DBG> EXAMINE %VMR(0:5) 
O\$VMR 

(0): 


(1): 
(2) % 
(3): 
(4): 


(5). 
DBG> e\aieieopERaNDS ~ BPC 
PROGSMAIN\%LINE 12: VVADDF/1 V0,V1,V2 
VO contains: 
O\%V0(0): 7.0000000 
O\$V0(2):; 7.0000000 
O\%V0(4): 7.0000000 
Vl contains: 
O\$V0(0): 4.0000000 
O\$V0(2): 4.0000000 
O\SV0(4): 4.0000000 
V2 contains: 
O\%V0(0): 5.0000000 
O\$V0(2): 5.0000000 
O\3V0(4): 5.0000000 


oOrOr OF 


DBG> 


Debugging Vectorized Programs 
11.4 Examining and Depositing Vector Instructions 


The next example shows a masked operation that loads data from memory to a 
vector register. Comments, keyed to the callouts, follow the example. 


DBG> EXAMINE %VLR 


O\SVLR: 6 
DBG> EXAMINE %VMR(0:5) 
0\3VMR 

(0): 1 

(1): 0 

{2):s At 

(3): 0 

(4): 1 


(oO 
DBG> EXAMINE/OPERANDS .3PC @ 
PROGSMAIN\%LINE 31+12: VLDL/1 ARR+8, #4, V0 @ 
PROGSMAIN\ARR(3) (address 1024) contains 35 
V0 contains: 
o\svo(0): 0 O 
O\%V0(2): 0 
O\SV0 (4): 0 
DBG> EXAMINE ARR (1:8) 
PROGSMAIN\ARR 
(l}s 9 
(2): 17 
(3): 35 
(4): 713 
(5): 81 
(6)? 6 
(7): 7 
(8)}s 49 
DBG> 


6 


The comments that follow refer to the callouts in the previous example: 


@ The EXAMINE/OPERANDS command shows that a VLDL instruction is 
about to be executed. The instruction will load longword-integer data from 
array ARR, starting at ARR+8 bytes, into register VO, as illustrated in 
Figure 11-1. Figure 11-1 shows the contents of VO after the instruction 
has been executed. Note that array ARR is indexed 1 to n, not 0 to n-1 
(FORTRAN example). 


© The stride value (#4) of the VLDL instruction specifies the number of bytes 
between the start addresses of array elements. 


© The instruction operand ARR+8 denotes the start of array element 3, ARR(8). 
The EXAMINE/OPERANDS command displays only the first element of array 
ARR that is operated upon (see item @). 


© The current values of VLR and VMR will cause the VLDL instruction to load 
the contents of array elements ARR(3), ARR(5), and ARR(7) into register 
elements V0(0), V0(2), and V0(4), respectively. The EXAMINE/OPERANDS 
command shows the contents of VO before the instruction has been executed. 


@ For reference, the EXAMINE ARR(1:8) command displays the full range of 
array elements that are associated with the load operation. 
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Figure 11-1 Masked Loading of Array Elements from Memory into a Vector 


Register 


Instruction: VLDL/1 ARR+8,#4,V0 





ZK-1937A-GE 


11.4.2 Depositing Vector Instructions 


The techniques for depositing VAX scalar instructions also apply to depositing 
vector instructions. (See Section 4.3.2.) For example, the following command 
deposits a masked VVMULF vector instruction at the current PC address: 


DBG> DEPOSIT/INSTRUCTION .%PC = "VVMULF/0 V2,V3,V7" 
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Note the following additional information when depositing vector instructions. 
(See the VAX MACRO and Instruction Set Reference Manual for details about 
instruction opcodes.) 


The regnum.rw operand of the MxVP and VSYNC instructions is generated as 
a short literal. 


Do not specify a vector control word when depositing a vector instruction. 
The debugger constructs the vector control word based on the instruction and 
instruction qualifiers, if any, and encodes it using immediate mode. 


The value of an immediate argument of a VSMERGEx instruction is 
interpreted according to the data type associated with that instruction. 
For example, the src argument for a VSMERGEF instruction is interpreted 
as a F_floating value, and so on. For VSMERGE without a type suffix, the 


debugger interprets a literal src operand as a quadword integer in the current 
radix. 
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11.5 Using a Mask When Examining Vector Registers or 
Instructions 
Section 11.4.1 explains how the command EXAMINE/OPERANDS .%PC displays 


vector instruction operands, depending on whether or not the operation is masked 
by VMR. 


This section explains how to specify an arbitrary mask in order to simulate or 
override the effect of VMR and obtain the following results: 


¢ Display only certain elements of a vector register or of an array in memory 


e Override the operand masking (if any) that might be associated with an 
examined instruction 


You specify a mask by using the /T[MASK or /FMASK qualifier with the 
EXAMINE command. 


Note 


- The remainder of this section describes use of the /TMASK and /FMASK 
qualifiers when examining vector registers. Unless indicated otherwise, 
the discussion also applies to use of these qualifiers when examining 
memory arrays. 


The /TMASK qualifier applies the EXAMINE command only to the elements of 
the examined register that correspond to the set bits (bit value: 1) of the mask. 
The /FMASK qualifier applies the EXAMINE command only to the elements that 
correspond to the clear bits (bit value: 0) of the mask. 


The current value of VLR limits the highest element of a vector register that 
you can examine. But the value of VLR does not affect examining an array in 
memory. 


You can optionally specify a mask (in the form of a mask address expression) with 
the /TMASK and /FMASK qualifiers: 


¢ Section 11.5.1 describes use of these qualifiers with the default mask, which 
is VMR. 


¢ Section 11.5.2 describes use of these qualifiers with some arbitrary slice of 
VMR as the mask. 


¢ Section 11.5.3 describes use of these qualifiers with a mask other than VMR. 


11.5.1 Using VMR as the Default Mask 


By default, if you do not specify a mask with the EXAMINE/TMASK or 

EXAMINE/FMASK command, VMR is used as the mask. That is, the EXAMINE 
command is applied only to the elements of the vector register that correspond to 
the set bits (in the case of /TMASK) or clear bits (in the case of /FMASK) of VMR. 


In the examples that follow, VLR has the value 6 and VMR(0:VLR-1) has the 
following set of values: 
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DBG> EXAMINE %VMR(0:%VLR-1) 


O\SVMR 
(0): 1 
(1): 0 
(2): 1 
(3)% 0 
(4): 1 
(5) 3 0 

DBG> 


The following command displays the value of V3 without using a mask. All 
elements of V3 from 0 to VLR-1 are displayed: 


DBG> EXAMINE %V3 


0\8V3 
(0): 17 
(1): 138 
(2): 3 
(3): 9 
(4): 51 
(5): 252 

DBG> 


The following command displays the elements of V3 (in the range from 0 to 
VLR-1) for which VMR(z) has the value 1: 


DBG> EXAMINE/TMASK %V3 


0\8V3 
(0): 17 
(2): 3 
(4); 51 
DBG> 


The following command displays the elements of V3 (in the range from 0 to 
VLR-1) for which VMR(i) has the value 0: 


DBG> EXAMINE/FMASK %V3 


0\8V3 
(1): 138 
(3): 9 
(5): 252 
DBG> 


In the following example, the /FMASK qualifier is used when examining an 
instruction and its vector-register operands. The EXAMINE/OPERANDS/FMASK 
command displays the register-operand elements (in the range from 0 to VLR-1) 
for which VMR(i) has the value 0: 


DBG> EXAMINE/OPERANDS/FMASK .%PC 
_ PROGSMAIN\SLINE 341+16: VVEQLL V0,V1 
VO contains: 
O\8VO(1): 0 
O\8V0(3): 0 
O\SV0(5): 0 


V1 contains: 
O\SV1 (1): 
O\$V1 (3): 
O\SV1 (5): 


oOo oO 


DBG> 
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11.5.2 Using a Slice of VMR as the Mask 


If you specify a slice of VMR with the EXAMINE/TMASK or EXAMINE/FMASK 
command, the output is displayed according to the following conventions: 


1. 


The number of mask elements specified limits the number of register element 
that you can examine. For example: 


DBG> EXAMINE %VLR 


O\SVLR: 12 
DBG> EXAMINE %VMR(3:5) 
O\S$VMR 

(3): 1 

(4): 1 

(5): 1 
DBG> EXAMINE/TMASK=(%VMR(3:5)) %V0(3:10) 
O0\%VO 

(3):: 9 

(4): 51 

(5}% 252 
DBG> 


Note the use of parentheses when specifying a mask with the /TMASK 
qualifier. 


The lowest specified element of the mask is applied to the lowest specified 
element of the register. For example, EXAMINE/TMASK %V0(4:7) applies 
VMR(0) to V0(4), VMR(1) to V0(5), and so on. If the lowest specified elements 
of the mask and register do not match, the debugger lists both the mask 
elements and the register elements that are operated on and issues a | 
message. For example: 

DBG> EXAMINE %VLR 


O\SVLR: 12 
DBG> EXAMINE %VMR(4:7) 


O\SVMR 
(4): 1 
(5): 0 
(6): 1 
(7): 


DBG> EXAMINE/TMASK= (%VMR (4:7) ) 6V0 (3:10) 
$DEBUG-I-MASKMISMATCH, mask/target subscripts do not match, 
displaying mask 

0\sv0 
S$VMR (4): 
$V0(3): 
SVMR (6) : 
$V0(5): 2 
SVMR (7): 
$V0 (6): 5 

DBG> 


ui 
He YM Fr wOF 


11.5.3 Using a Mask Other Than VMR 


If you specify a mask address expression other than VMR with the EXAMINE 
/TMASK or EXAMINE/FMASK command, the value at that address is used as 
the mask, subject to the following conventions: 


If the mask address expression denotes a Boolean array, its values are used 
as the mask in the same basic way that VMR is used in the default case. In 
the following example, BOOL_ARR, a 4-element Boolean array variable, is 
used as the mask: 
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DBG> EXAMINE %VLR 
O\SVLR: 6 

DBG> EXAMINE BOOL ARR 
PROGSMAIN\BOOL ARR 


(0): 0 
(1): 0 
(2): 1 
(3): 0 


DBG> EXAMINE/FMASK=(BOOL ARR) %V0 
$DEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying 
specified mask 


0\$v0 
BOOL ARR(0): 0 
80 (0): 17 
BOOL_ARR(1): 0 
8V0(1): 138 
BOOL ARR(3): 0 
$V0 (3) : 9 

DBG> 


As shown in the example, when you use a mask other than VMR, the 
debugger displays both the mask elements and the register elements that are 
operated on and issues a message. 


e Ifthe mask address expression denotes a non-Boolean array, the least 
significant bit of each array element is used as the mask for the corresponding 
element of the register. 


¢ Ifthe mask address expression denotes a Boolean scalar type, its value is 
used as the mask for the first element of the register. No other elements are 
examined. In the following example, BOOL_VAR, a single-element Boolean 
variable, is used as the mask: 


DBG> EXAMINE BOOL VAR 

PROGSMAIN\BOOL VAR: 1 

DBG> EXAMINE/TMASK=(BOOL VAR) %V0 

SDEBUG-I-MASKNOTVMR, mask used is not %VMR, displaying 
specified mask 


0\8V0 
BOOL VAR: = 1 
30 (0): 17 
DBG> 


e Ifthe mask address expression denotes any other type, its least significant 
bit value is used as the mask for the first element of the register. No other 
elements are examined. 


¢ The number of mask elements specified limits the number of register elements 
that you can examine, as when the mask is VMR (see Section 11.5.2). 


e For a multielement mask, the lowest specified element of the mask is applied 
to the lowest specified element of the register, as when the mask is VMR (see 
Section 11.5.2). 


11.6 Examining Composite Vector Address Expressions 


When using the EXAMINE command, you can specify various forms of composite 
address expressions—expressions that include byte offsets from a given address. 
For example, if X is an integer variable, the following EXAMINE command 
displays the value currently stored at the memory location that is 6 bytes beyond 
the address of X: 
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DBG> EXAMINE X + 6 
MOD3\X+6: 274903 
DBG> 


The examples in this section show how to specify composite address expressions 
of a form that might be appropriate for a vectorized program. 


The next example shows how you might verify the effect of a VSCATL instruction. 
The instructions shown are decoded from a FORTRAN program. Comments, 
keyed to the callouts, follow the example. 


DBG> EXAMINE %VLR 
O\SVLR: 5 
DBG> EXAMINE/OPERANDS .3PC @ 
PROGISMAIN\SLINE 9+32: VSCATL V7,W*-804(R11) ,V9 
V7 contains: 
O\$v7(0): 11 @ 
O\3V7(1): 13 
O\3V7(2): 15 
O\3V7 (3): 17 
O\3V7(4): 19 


W*-804 (R11) PROGISMAIN\ARRX(1) (address 1820) contains 0 3) 
V9 contains: 


o\sv9(0): 0 @ 
O\SV9(1): 8 
O\$V9(2): 16 
O\$V9(3): 24 


O\SV9(4): 32 
DBG> SHOW SYMBOL/TYPE ARRX @ 
data PROGI$MAIN\ARRX 
array descriptor type, 1 dimension, bounds: [{1:200], size: 800 bytes 
cell type: atomic type, longword integer, size: 4 bytes 
DBG> EXAMINE ARRX(1) + .%V9(0:%VLR-1) 


PROGISMAIN\ARRX (1) : 0 
PROG1$MAIN\ARRX (3) : 0 
PROGISMAIN\ARRX (5) : 0 
PROG1SMAIN\ARRX (7) : 0 
PROG1SMAIN\ARRX (9) : 0 


DBG> STEP/INSTRUCTION @ 
stepped to PROGISMAIN\$LINE 9+40: MOVZBL  1*#64,AP 
DBG> EXAMINE ARRX(1) + .3V9(0:3VLR-1) 


PROGISMAIN\ARRX (1) : tt 
PROG1$MAIN\ARRX (3) : i3 
PROG1$MAIN\ARRX (5) : 15 
PROGL1SMAIN\ARRX (7) : 17 
PROG1SMAIN\ARRX (9) : 19 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ The EXAMINE/OPERANDS command shows that a VSCATL instruction is 
about to be executed. The instruction will transfer longword-integer (4-byte) - 
data from register V7 into memory locations. These locations are determined 
by adding offset values, contained in register V9, to a base address. 


Register V7 contains the longword-integer values to be transferred to memory. 


The base address specified as an operand to the VSCATL instruction is 
symbolized as ARRX(1), which denotes element 1 of array ARRX. 


Register V9 contains the offset from the base address, in bytes, of each target 
vector element in memory. 


The SHOW SYMBOL/TYPE command indicates that ARRX is an array of 
contiguous longword integers. 


o 6 89 
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@ The EXAMINE command displays the values of the target vector elements in 


memory. The address expression specified uses the offset values contained in 
register V9 to set the start address of successive vector elements in memory, 
relative to ARRX(1), the base address. The debugger symbolizes the locations 
of vector elements in memory in terms of the elements of array ARRX. In 
this example, vector elements begin every 8 bytes, coinciding with every other 


element of array ARRX. Because the VSCATL instruction has not yet been 
executed, all of the vector elements in memory contain the value zero. 


@ The STEP/INSTRUCTION command executes the VSCATL instruction and 
suspends execution at the next instruction, MOVZBL. 


© As in item O, the EXAMINE command displays the values of the target 
vector elements in memory. Now the contents of memory show that the 
values have been transferred from register V7. 


The next example shows how to specify a more complex vector address expression 


with the EXAMINE command. 


Assume that array ARRZ has contiguous quadword-integer (8-byte) elements. 
The fourth EXAMINE command in the example displays the values of vector 
elements in memory, starting at element ARRZ(1). As in the previous example, 
the debugger symbolizes the locations of vector elements in terms of the array 
elements. The location of successive vector elements relative to ARRZ(1) is 
computed by adding the values contained in registers V1 and V8 to specify a 
combined offset for a particular element. The order in which vector elements are 
displayed is determined by cycling through all the values in the last specified 
register (V3(0:2)) for each value in the first specified register (V1). In this 
example, the values of all vector elements are zero. 


DBG> EXAMINE %VLR 


O\SVLR: 4 
DBG> EXAMINE $V1 
O\$V1 

(0): 0 

(1): 4 

(2): 8 

(218 12 
DBG> EXAMINE $V3 
O\3V1 

(0): 0 

(1): 8 

(2): 16 

(3): 24 
DBG> EXAMINE ARRZ(1) + .%V1(0:3) + .%V3(0:2) 
PROG4S$MAIN\ARRZ (1) : 0 ! ARRZ(1)+0+0 
PROG4SMAIN\ARRZ (2) : 0 ! ARRZ(1)+0+8 
PROG4SMAIN\ARRZ (3) : 0 ! ARRZ (1) +0+16 
PROG4SMAIN\ARRZ (1) +4: 0 ! ARRZ(1)+4+0 
PROG4SMAIN\ARRZ (2) +4: 0 ! ARRZ(1)+4+8 
PROG4SMAIN\ARRZ (3) +4: 0 ! ARRZ (1) +4+16 
PROG4SMAIN\ARRZ (2) : 0 ! ARRZ(1)+8+0 
PROG4SMAIN\ARRZ (3) : 0 ! ARRZ(1)+8+8 
PROG4SMAIN\ARRZ (4): 0 ! ARRZ(1)+8+16 
PROG4SMAIN\ARRZ (2) +4: 0 ! ARRZ(1)+12+0 
PROG4SMAIN\ARRZ (3) +4: 0 ' ARRZ(1)+12+8 
PROG4SMAIN\ARRZ (4) +4: 0 ! ARRZ(1)+12+16 


DBG> 
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11.7 Displaying the Results of Vector Floating-Point Exceptions 


When a vector instruction causes a floating-point exception in a vector element, 
the exception result is encoded into the corresponding element of the destination 
register. 


In such cases, you can use the EXAMINE/FLOAT command to display the 
decoded exception message in the associated register element. This technique 
enables you to identify a floating-point exception that is still pending delivery, as 
illustrated in Section 11.8. The following example shows that a vector instruction 
caused a floating divide-by-zero exception in element 2 of register V5: 


DBG> EXAMINE/FLOAT $%V5 


O\SV5 
(0): 297.2800 
(1):  87.41499 
(2): Reserved operand, encoded as floating divide by zero 
(3) “173.8650 
DBG> 


If the program copies values from vector registers into memory, you can apply 
the EXAMINE/FLOAT command to the memory location and display the decoded 
information, as you would for a vector register. 


The following table identifies the decoded debugger message for each type of 
vector floating-point exception. 


Exception Debugger Message 
Floating underflow Reserved operand, encoded as floating underflow 
Floating divide by zero Reserved operand, encoded as floating divide by zero 


Floating reserved operand Reserved operand, encoded as floating reserved operand 
Floating overflow Reserved operand, encoded as floating overflow 


11.8 Controlling Scalar-Vector Synchronization 


To achieve high performance, the VAX scalar and vector processors operate 
concurrently as much as possible. The scalar processor passes any vector 
instructions to the vector processor and then continues executing scalar 
instructions while the vector processor executes vector instructions. 


In some cases, the operation of the two processors must be synchronized to ensure 
correct program results. By using synchronizing instructions such as SYNC, 
MSYNC, and VSYNC, the program forces certain operations to complete before 
others are initiated. See the VAX MACRO and Instruction Set Reference Manual 
for more information about these instructions and scalar-vector synchronization. 


If the program has been vectorized by the compiler (for example, the VAX 
FORTRAN compiler), the necessary synchronizing instructions are automatically 
generated. However, VAX MACRO programmers need to code synchronizing 
instructions explicitly. 


By default, the debugger does not force scalar-vector synchronization during 
program execution except for its own internal purposes. The program executes 
as if it were running without debugger control, and synchronization is controlled 
entirely by the program. This default mode of operation is established by the 
SET VECTOR_MODE NOSYNCHRONIZED command. 
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When you use the debugger in the default, nonsynchronized vector mode, certain 
vector operations might be in an interrupted state when program execution is 
suspended at a breakpoint, watchpoint, or at the completion of a STEP command. 
For example: 


e An exception caused by a vector instruction might be pending delivery. 


¢ An operation that transfers data between vector registers and scalar memory 
might not have completed. Therefore, examining the contents of memory or 
vector registers might yield unpredictable results. 


To eliminate potential confusion in such cases, enter the command 
SYNCHRONIZE VECTOR_MODE. It forces immediate synchronization between 
the scalar and vector processors. Entering this command is equivalent to issuing 
a SYNC and an MSYNC instruction at the location in the program at which 
execution is suspended. The effect is as follows: 


e Any exception that was caused by a vector instruction and was still pending 
delivery is immediately delivered. Note that forcing the delivery of a pending 
exception triggers an exception breakpoint or tracepoint (if one was set) 
or invokes an exception handler (if one is available at that location in the 
program). 


e Any read or write operation between vector registers and either the general 
registers or memory is completed immediately—that is, any vector memory 
instruction that was still being executed completes execution. 


The following MACRO example shows the effect of the SYNCHRONIZE 
VECTOR_MODE command. Comments, keyed to the callouts, follow the 
example. 


DBG> STEP @ 

stepped to .MAIN.\SUB\%LINE 99 
99: VVDIVD v1,V0,V2 

DBG> stEeP @ 

stepped to .MAIN.\SUB\%LINE 100 


100: CLRL RO 
DBG> EXAMINE/FLOAT %v2 © 
0\sVv2 
POys 13.53400 
(Ty: Reserved operand, encoded as floating divide by zero 


[2] 247.2450 


DBG> SYNCHRONIZE VECTOR MODE 4) 
_ SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%SLINE 100 
100: CLRL RO 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ This STEP command suspends program execution on line 99, just before 
a VVDIVD instruction is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 


@ This STEP command executes the VVDIVD instruction. Note, however, that 
the exception is not delivered at this point in the execution of the program. 
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© The EXAMINE/FLOAT command displays a decoded exception message in 
element 1 of the destination register, V2 (see Section 11.7). This confirms 
that a floating-point divide-by-zero exception was triggered and is pending 
delivery. 


© The SYNCHRONIZE VECTOR_MODE command forces the immediate 
delivery of the pending vector exception. (Note that you might obtain a 
different set of diagnostic messages if your program were using the VVIEF 
rather than vector processor hardware.) 


An alternative to using the SYNCHRONIZE VECTOR_MODE command is to 
operate the debugger in the synchronized vector mode by entering the SET 
VECTOR_MODE SYNCHRONIZED command. This command causes the 
debugger to force automatic synchronization between the scalar and vector 
processors whenever a vector instruction is executed. Specifically, the debugger 
issues a SYNC instruction after every vector instruction and, in addition, an 
MSYNC instruction after any vector instruction that accesses memory. This 
forces the completion of all activities associated with the vector instruction that is 
being synchronized: 


e Any exception that was caused by a vector instruction is delivered before 
the next scalar instruction is executed. Note that forcing the delivery of a 
pending exception triggers an exception breakpoint or tracepoint (if one was 
set) or invokes an exception handler (if one is available at that location in the 
program). 


e Any read or write operation between vector registers and either the general 
registers or memory is completed before the next scalar instruction is 
executed. 


The following example shows the effect of the SET VECTOR_MODE 
SYNCHRONIZED command on the same instruction stream that was used 
in the previous example. Comments, keyed to the callouts, follow the example. 


DBG> SHOW VECTOR MODE 
Vector mode is nonsynchronized 
DBG> SET VECTOR MODE SYNCHRONIZED 0 
DBG> SHOW VECTOR MODE 
Vector mode is synchronized 
DBG> STEP 
stepped to .MAIN.\SUB\SLINE 99 
99: VVDIVD V1,V0,V2 
DBG> STEP 
SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\%LINE 100 
100: CLRL RO 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ The command SET VECTOR_MODE SYNCHRONIZED causes the debugger 
to force automatic synchronization between the scalar and vector processors 
whenever a vector instruction is executed. 


@ This STEP command suspends program execution on line 99, just before a 
VVDIVD instruction is executed. Assume that, as in the previous example, 
the instruction will trigger a floating-point divide-by-zero exception. 
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© This STEP command executes the VVDIVD instruction, which triggers the 
exception. Note that the vector exception is delivered immediately because 
the debugger is being operated in synchronized vector mode. 


Note that, in addition to SYNCHRONIZE VECTOR_MODE and SET VECTOR_ 
MODE SYNCHRONIZED, a few other debugger commands can affect 
synchronization—for example, SET WATCH. 


11.9 Calling Routines That Might Affect the Program’s Vector State 
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The CALL command’s /[NO]JSAVE_VECTOR_STATE qualifiers enable you to 
control whether the current state of the vector processor is saved and then 
restored when a routine is called. 


The state of the VAX vector processor comprises the following: 
e The values of the vector registers and vector control registers 


e Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 


When you use the CALL command to execute a routine, execution of the routine 
might change the state of the vector processor as follows: 


e By changing the values of vector registers or vector control registers 
¢ By causing a vector exception 


e By causing the delivery of a vector exception that was pending when the 
‘CALL command was issued 


The CALL/SAVE_VECTOR_STATE command specifies that the state of the vector 
processor that exists before the CALL command is issued is restored by the 
debugger after the called routine has completed execution. This ensures that, 
after the called routine has completed execution: 


e Any vector exception that was pending delivery before the CALL command 
was issued is still pending delivery 


¢ No vector exception that was triggered during the routine call is still pending 
delivery 


¢ The values of the vector registers are identical to their values before the 
CALL command was issued 


The CALL/NOSAVE_VECTOR_STATE command, which is the default, specifies 
that the state of the vector processor that exists before the CALL command is 
issued is not restored by the debugger after the called routine has completed 
execution. In this case, the state of the vector processor after the routine call 
depends on the effect (if any) of the called routine. 


The /[NO]JSAVE_VECTOR_STATE qualifiers have no effect on the VAX general 
(scalar) registers. The values of these registers are always saved and restored 
when you execute a routine with the CALL command. 
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11.10 Displaying Vector Register Data in Screen Mode 


In screen mode, a register display shows the current values of the VAX general 
registers. (See Section 7.2.5.) 


To display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 7.6.1.) 


For example, the following command creates a DO display named V2_DISP that 
shows the contents of elements 4 to 7 of register V2 (FORTRAN array syntax). 
The display is automatically updated whenever the debugger gains control from 
your program: . 


DBG> DISPLAY V2_DISP AT RQ2 DO (EXAMINE %V2(4:7)) 
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This chapter describes features of the debugger that are specific to tasking 
programs (also called multithread programs). Tasking programs have multiple 
threads of execution within a VMS process and include the following: 


e Programs written in any language that use DECthreads or POSIX 1003.4a 
services. 


¢ Programs that use language-specific tasking services (services provided 
directly by the language). Currently, Ada is the only language with built-in 
tasking services that the debugger supports. 


Within the debugger, the term task denotes such a flow of control, regardless of 
the language or implementation. The debugger’s tasking support applies to all 
such programs. 


In this chapter, any DECthreads-specific or language-specific information is 
identified as such. Section 12.1 gives a cross reference between DECthreads 
terminology and Ada tasking terminology. 


The features in this chapter enable you to do functions such as the following: 
¢ Display task information. 


¢ Modify task characteristics to control task execution, priority, state 
transitions, and so on. 


¢ Monitor task-specific events and state transitions. 


When using these features, remember that the debugger might alter the 
behavior of a tasking program from run to run. For example, while you are 
suspending execution of the currently active task at a breakpoint, the delivery of 
an asynchronous system trap (AST) or a POSIX signal as some I/O is completed 
might make some other task eligible to run as soon as you allow execution to 
continue. . 


For information about DECthreads or POSIX threads, see the corresponding 
documentation in the VMS documentation set. For information about Ada tasks, 
see the VAX Ada documentation. 


The debugging of multiprocess programs (programs that run in more than one 
process) is described in Chapter 10. 
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12.1 Comparison of DECthreads and Ada Terminology 


Table 12-1 compares DECthreads and Ada terminology and concepts. 


Table 12-1 Comparison of DECthreads and Ada Terminology 


DECthreads Terminology Ada Terminology Description 

Thread Task The flow of control within a 
process 

Thread object Task object — The data item that represents 


the flow of control 


Object name or expression Task name or expression The data item that represents 
the flow of control 


Start routine Task body The code that is executed by the 
flow of control 


Not applicable Master task A parent flow of control 
Not applicable Dependent task A child flow of control that is 
controlled by some parent 
Synchronization object Rendezvous construct Method of synchronizing fiows 
(mutex, conditionvariable) such as entry call or of control 
accept statement 
Scheduling policy and Task priority Method of scheduling execution 
scheduling priority 
Alert operation Abort statement Method of canceling a flow of 
control 
Thread state Task state Execution state (waiting, ready, 
running, terminated) 
Thread creation attribute Pragma Attributes of the parallel entity 
(priority, scheduling policy, 
and so on) 


12.2 Sample Tasking Programs 


The following sections present sample tasking programs with common errors that 
you might encounter when debugging tasking programs: 


¢ Section 12.2.1 describes a C program that uses DECthreads services 


e Section 12.2.2 describes an Ada program that uses the built-in Ada tasking 
services 


Some other examples in this chapter are derived from these programs. 


12.2.1 Sample C Multithread Program 
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Example 12-1 is a multithread C program that shows incorrect use of condition 
variables, resulting in blocking. 


Explanatory notes are included after the example. Following these notes are 
instructions showing how to use the debugger to diagnose the blocking by 
controlling the relative execution of the threads. 


In the example, the initial thread creates two worker threads that do some 
computational work. Once the worker threads are created, a SHOW TASK/ALL 
command will show four tasks, each corresponding to a thread (Section 12.4 
explains use of the SHOW TASK command). 


Debugging Tasking Programs 
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¢ 9%TASK 1 is the initial thread, which executes from main(). (Section 12.3.3 
defines task IDs, such as TASK 1.) 


¢ 9%TASK 2 is the null thread, which does environment work in the background. 
%TASK 2 executes when no other threads are eligible to execute. 


© %TASK 3 and “TASK 4 are the worker threads. 


In the example, a synchronization point (a condition wait) has been placed in the 
workers’ path at line 3893. (The comment starting at line 3877 indicates that 

a straight call such as this one is incorrect programming and shows the correct 
code.) 


When the program executes, the worker threads are busy computing when the 
initial thread broadcasts on the condition variable. The first thread to wait on 
the condition variable detects the initial thread’s broadcast and clears it, leaving 
any remaining threads stranded. Execution is blocked and the program cannot 
terminate. 


Example 12-1 Sample C Multithread Program 


S717. 
3778 
3779 
3780 
3781 
3782 
S783 
3784 
3785 
3786 
3787 
3788 
3799 
3790 
3791 
3792 
3193 
3794 
3795 
3796 
3787 
3798 
3799 
3800 
3801 
3802 
3803 
3804 
3805 
3806 
3807 
3808 
3809 
3810 
3811 
3812 
3813 
3814 
3815 
3816 


/* DEFINES */ 


#define NUM WORKERS 2 /* Number of worker threads x/ 
/* MACROS os 
#define check(status,string) \ 
if (status == -1) perror (string); \ 

/* GLOBALS +/ 
int cv_predl; /* Condition Variable predicate */ 
pthread_mutex t cv_mutex; /* Condition Variable mutex * / 
pthread cond t cv; /* Condition Variable 7 
pthread_mutex t print_mutex; /* Print mutex */ 
/* ROUTINES * | 


static pthread_startroutine t 
worker routine (pthread_addr_t arg); 


main () 

{ 

pthread_t threads[NUM WORKERS]; /* Worker threads 7] 
int status; /* Return statuses */ 
int exit; /* Join exit status x/ 
int result; /* Join result value */ 
int i; /* Loop index */ 
/* Initialize mutexes */ 


status = pthread_mutex_init (&cv_mutex, pthread_mutexattr_default) ; 
check (status, "cv mutex initilization bad status"); 

status = pthread | mutex_ init (&print_mutex, pthread_mutexattr_ default) ; 
check (status, "print | mutex intialization bad status"); 


/* Initialize condition variable */ 
status = pthread_cond_init (&cv, pthread_condattr default) ; 
check (status, "cv condition init bad status"); 


/* Initialize condition variable predicate. a7 
cv_predl = 1; 


/* Create worker threads */ 
for (1 = 0; i< NUM_WORKERS; i++) { 


(continued on next page) 
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aa 12-1 (Cont.) Sample C Multithread Program 
817 


aie 
3819 
3820 
3821 
3822 
3823 
3824 
3825 
3826 
3827 
3828 
3829 
3830 
3831 
3832 
3833 
3834 
3835 
3836 
3837 
3838 
3839 
3840 
3841 
3842 
3843 
3844 
3845 
3846 
3847 
3848 
3849 
3850 
3851 
3852 
3853 
3854 
3855 
3856 
3857 
3858 
3859 
3860 
3861 
3862 
3863 
3864 
3865 
3866 
3867 
3868 
3869 
3870 
3871 
3872 
3873 
3874 
a679 
3876 
3877 
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status = pthread create ( 

&threads [i], 

pthread_attr default, 

worker routine, 

0); 
check (status, "threads create bad status"); 
} 


/* Set cv_predl to false; do this inside the lock to insure visibility. */ 


status = pthread_mutex_ lock (&cv_mutex); 
check (status, "cv_mutex lock bad status"); 


cv_predl = 0; 13) 


status = pthread_mutex_unlock (&cv_mutex); 
check (status, "cv_mutex unlock bad status"); 


/* Broadcast. */ 
status = pthread_cond_broadcast (&cv); 0 
check (status, "CV broadcast bad status"); 


/* Attempt to join both of the worker threads. */ 

for (i = 0; i < NUM_WORKERS; i++) { 
exit = pthread_join (threads[i], (pthread_addr_t*) &result); 
check (exit, "threads join bad status"); 
} 

} 


static pthread_startroutine t 
worker routine (arg) 


pthread _ addr t arg; 6) 
{ 

int sum; 

int iterations; 

int count; 

int status; 


/* Do many calculations ay 
for (iterations = 1; iterations < 10001; iterations++) { 
sum = 1; 


for (count = 1; count < 10001; count++) { 
sum = sum + count; 
} 

} 


/* Printf may not be reentrant, so allow 1 thread at a time */ 
status = pthread_mutex_lock (&print_mutex) ; 

check (status, "print_mutex lock bad status"); 

printf (" The sum is %d \n", sum); 

status = pthread_mutex_unlock (&print_mutex) ; 

check (status, "print_mutex unlock bad status"); 


/* Lock the mutex associated with this condition variable. pthread_cond_wait will */ 
/* unlock the mutex if the thread blocks on the condition variable. xf 


status = pthread_mutex lock (&cv_mutex); 
check (status, "cv_mutex lock bad status"); 


/* In the next statement, the correct condition-wait syntax would be to loop */ 
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Example 12-1 (Cont.) Sample C Multithread Program 


3878 
3879 
3880 
3881 
3882 
3883 
3884 
3885 
3886 
3887 
3888 
3888 
3890 
3891 
S89Z 
3893 
3894 
3895 
3896 
3897 
3898 
3899 
3900 
3901 
3902 
3903 


/* around the condition-wait call, checking the predicate associated with the */ 
/* condition variable. This would guard against condition waiting on a condition */ 
/* variable that may have already been broadcast upon, as well as spurious wake */ 
/* ups. Execution would resume when the thread is woken AND the predicate is */ 
/* false. The call would look like this: a7 
/* af 
/* while (cv_predl) { a7 
‘hg status = pthread_cond wait (&cv, &cv_mutex); i): 
/* check (status, "cv condition wait bad status"); ay 
pe -3 ee 
Bs ef 
/* A straight call, as used in the followingt code, might cause a thread to +f 
/* wake up when it should not (spurious) or become permanently blocked, as */ 
/* should one of the worker threads here. 7 
status = pthread_cond wait (&cv, &cv_mutex); 7) 


check (status, "cv condition wait bad status"); 


/* While blocking in the condition wait, the routine lets go of the mutex, but * 
/* it retrieves it upon return. 7 


Status = pthread_mutex_unlock (&cv_mutex) ; 
check (status, "cv_mutex unlock bad status"); 


return (int)arg; 


} 


Key to Example 12-1: 


@ The first few statements of main() initialize the synchronization objects 


used by the threads, as well as the predicate that is to be associated with 
the condition variable. The synchronization objects are initialized with the 
default attributes. The condition variable predicate is initialized such that a 
thread that is looping on it will continue to loop. At this point in the program, 
a SHOW TASK/ALL display lists %TASK 1 and %TASK 2. 


The worker threads TASK 3 and “TASK 4 are created. Here the created 
threads execute the same start routine (worker_routine) and hence can reuse 
the same call to pthread_create with a slight change to store the different 
thread IDs. The threads are created using the default attributes and are 
passed an argument that is not used in this example. 


The predicate associated with the condition variable is cleared in preparation 
to broadcast. This ensures that any thread awaking off the condition variable 
has received a valid wake-up and not a spurious one. Clearing the predicate 
also prevents any new arrivals from waiting on the condition variable because 
it has been broadcast or signaled upon. (The desired effect depends on correct 
coding being used for the condition wait call at line 3893, which is not the 
case in this example.) 


The initial thread issues the broadcast call almost immediately, so that none 
of the worker threads should yet be at the condition wait. A broadcast should 
wake any threads currently waiting on the condition variable. 


As the programmer, you should ensure that a broadcast is seen, by either 
ensuring that all threads are waiting on the condition variable at the time 
of broadcast or ensuring that an associated predicate is used to flag that the 
broadcast has already happened. (Such measures have been left out of this 
example purposely.) 
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© The initial thread attempts to join with the worker threads to ensure that 
they exited properly. 


© When the worker threads execute worker_routine, they spend time doing 
many computations. This allows the initial thread to broadcast on the 
condition variable before either of the worker threads is waiting on it. 


@ The worker threads then proceed to execute a pthread_cond_wait call, 
performing locks around the call as required. It is here that both worker 
threads will block, having missed the broadcast. A SHOW TASK/ALL 
command entered at this point would show both of the worker threads 
waiting on a condition variable. (Once the program is deadlocked in this way, 
you must press Ctrl/C to return control to the debugger.) 


The debugger enables you to control the relative execution of threads to diagnose 
problems of the kind shown in Example 12-1. In this case, you can suspend 

the execution of the initial thread and let the worker threads complete their 
computations so that they will be waiting on the condition variable at the time of 
broadcast. The following procedure explains how: 


1. At the start of the debugging session, set a breakpoint on line 3836 to suspend 
execution of the initial thread just prior to broadcast. 


2. Enter the GO command to execute the initial thread and create the worker 
threads. 


3. At this breakpoint, which causes the execution of all threads to be suspended, 
put the initial thread on hold with the SET TASK/HOLD %TASK 1 command. 


4. Enter the GO command to let the worker threads continue execution. The 
initial thread is on hold and cannot execute. 


5. When the worker threads block on the condition variable, press Ctrl/C to 
return control to the debugger at that point. A SHOW TASK/ALL command 
should indicate that both worker threads are suspended in a condition wait 
substate. (If not, enter GO to let the worker threads execute, then press Ctrl 
/C, and enter SHOW TASK/ALL, repeating the sequence until both worker 
threads are in a condition wait substate.) 


6. Enter the SET TASK/NOHOLD %TASK command 1 and then the GO 
command to allow the initial thread to resume execution and broadcast. 
This will enable the worker threads to join and terminate properly. 


12.2.2 Sample Ada Tasking Program 


Example 12-2 is an Ada tasking program. The labels (<<B1>>, and so on) in the 
example mark points of interest where breakpoints could be set and the state of 
each task observed. If you were to run the example under debugger control, you 
could enter the following command to set breakpoints at each label and display 
the current state of each task at the breakpoints (Section 12.4 explains how to 
use the SHOW TASK command): 


DBG> SET BREAK B1,B2,B3,B4,B5,B6,B7 DO (SHOW TASK/ALL) 
The program creates four tasks: 


e An environment task that runs the main program, TASK_EXAMPLE. This 
task is created before any library packages are elaborated (in this case, 
TEXT_IO). The environment task has the task ID TASK 1 in the SHOW 
TASK displays (Section 12.3.3 defines task IDs). 
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e A task object named FATHER. This task is declared by the main program and 
designated %TASK 2 in the SHOW TASK displays. 


e A single task named MOTHER. This task is declared by the main program 
and designated %TASK 3 in the SHOW TASK displays. 


e A single task named CHILD. This task is declared by task FATHER and 
designated %TASK 4 in the SHOW TASK displays. 


Example 12-2 Sample Ada Tasking Program 
1 -- Tasking program that demonstrates various tasking conditions. 


with TEXT _I0; use TEXT 10; 
procedure TASK EXAMPLE is @ 


3 
4 
5 
6 pragma TIME SLICE(0.0); -- Disable time slicing. @ 
7 
8 


task type FATHER TYPE is 


9 entry START; 
10 entry RENDEZVOUS; 
11 entry BOGUS; -- Never accepted, caller deadlocks. 
12 end FATHER TYPE; 
i 
14 FATHER : FATHER TYPE; @ 
15 
16 task body FATHER TYPE is 
iy, SOME_ERROR : exception; 
18 
19 task CHILD is @ 
20 entry 5; 
21 end CHILD; 
22 
23 task body CHILD is 
24 begin 
25 FATHER_TYPE.BOGUS; 
26 end CHILD; 
27 
28 -- CHILD deadlocks on call to its parent 
29 -- (parent does not have an accept 
30 -- statement for entry BOGUS). 
31 
32 begin -- (of FATHER TYPE body) 
33 
34 accept START do 
35 <<Bl>>  -- Main program is waiting for this rendezvous to 
36 ~~ complete; CHILD is suspended when it calls the 
37 -- entry BOGUS. 
38 null; 
39 end START; 
40 
41 PUT_LINE("FATHER is now active and"); @ 
42 PUT _LINE("is going to rendezvous with main program."); 
43 


(continued on next page) 
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Example 12-2 (Cont.) Sample Ada Tasking Program 


44 for-1..in-1..2: loop 

45 select 

46 accept RENDEZVOUS do 

47 PUT LINE("FATHER now in rendezvous with main program"); 
48 end RENDEZVOUS; 

49 or 

50 terminate; 

51 end select; 

52 

53 if I = 2 then 

54 raise SOME ERROR; 

59 end if; 

56 end loop; 

57 

58 exception 

59 when others => 

60 <<B2>>  -- CHILD is suspended on entry call to BOGUS. 

61 -- Main program is going to delay while FATHER terminates. 
62 ~- MOTHER is ready to begin executing. 

63 abort CHILD; 

64 <<B3>>  -- CHILD is now abnormal due to the abort statement. 
65 

66 raise; -- SOME ERROR exception terminates FATHER. 

67 end FATHER TYPE; 

68 

69 task MOTHERis © 

70 entry START; 

71 pragma PRIORITY (6); 

72 end MOTHER; 

ees 

74 task body MOTHER is 

fe begin 

76 accept START; 

77 <<B4>> -- At this point, the main program is waiting for its 
78 -~ dependents (FATHER and MOTHER) to terminate. FATHER 
79 -- is terminated. 

80 null; 

81 end MOTHER; 

82 

83 begin -- (of TASK_EXAMPLE) @ 

84 <<B5>>  -- FATHER is suspended at accept start. 

85 -- CHILD is suspended in its deadlock. 

86 -- MOTHER has activated and is ready to begin executing. 
87 FATHER. START; 

88 <<B6>> -- FATHER is suspended at its ‘select or terminate’ 
89 -- statement. 

90 

91 


92 FATHER.RENDEZVOUS; @ 
93  FATHER.RENDEZVOUS; ® 


94 loop 
95 -- This loop causes the main program to busy wait 
96 -- for the termination of FATHER, so that FATHER 
97 -- can be observed in its terminated state. 
98 if FATHER’ TERMINATED then 

. 99 exit; 

100 end if; 

101 delay 1.0; 


102 end loop; 


12-8 


(continued on next page) 


Debugging Tasking Programs 
12.2 Sample Tasking Programs 


Example 12-2 (Cont.) Sample Ada Tasking Program 


103 
104 
105 
106 
107 
108 
109 
110 


<<B7>>  -- FATHER has terminated by now with the unhandled 
-- exception SOME ERROR. CHILD no longer exists 
-- because its master (FATHER) has terminated. Task 
~- MOTHER is ready. 
MOTHER. START; 
-- The main program enters a wait-for-dependents state, 
‘-- so that MOTHER can finish executing. 
end TASK EXAMPLE; 


Key to Example 12-2: 


2) 


After all Ada library packages are elaborated (in this case, TEXT_IO), the 
main program is automatically called and begins to elaborate its declarative 
part (lines 5 to 82). 


To ensure repeatability from run to run, the example uses no time slicing (see 
Section 12.5.2). The 0.0 value for the pragma TIME_SLICE documents that 
the procedure TASK_EXAMPLE needs to have time slicing disabled (time 
slicing is disabled if the pragma TIME_SLICE is omitted or is specified with 
a value of 0.0). 


Task object FATHER is elaborated, and a task designated %TASK 2 is 
created. FATHER (%TASK 2) is created in a suspended state (see Table 12-3). 
and is not activated until the beginning of the statement part of the main 
program (line 83), in accordance with Ada rules. The elaboration of the task 
body on lines 16 to 67 defines the statements that tasks of type FATHER_ 
TYPE will execute. 


Task FATHER declares a single task named CHILD (line 19). A single task 
represents both a task object and an anonymous task type. Task CHILD is 
not created or activated until FATHER is activated. 


The only source of ASTs is this series of TEXT_IO.PUT_LINE statements 
(input-output completion delivers ASTs). 


A single task, MOTHER, is defined, and a task designated %TASK 3 is 
created. The pragma PRIORITY gives MOTHER a priority of 6. 


The tasks FATHER and MOTHER are activated in parallel while the main 
program waits. FATHER has no pragma PRIORITY and thus assumes a 
default priority of 7. Because this is higher than the priority of MOTHER, 
FATHER executes its activation first. Its activation consists of the elaboration 
of lines 16 to 31. 


When task FATHER is activated, it waits while its task CHILD is activated 
and a task designated TASK 4 is created. CHILD executes one entry call 
on line 25, and then deadlocks because the entry is never accepted (see 
Section 12.7.1). 


This is the first rendezvous that the main program makes with task FATHER. 
This rendezvous causes FATHER to be suspended at its first accept statement 
(line 34). Note that FATHER continues to execute past the end of its 
activation, even though MOTHER has not been activated. This is because 
VAX Ada attempts to continue tasks as far as they will go to minimize task 
switch overhead. When FATHER becomes suspended, MOTHER begins its 
activation, and executes lines 74 and 75. 
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© After tasks FATHER and MOTHER are activated, the main program 
(%TASK 1) is eligible to resume execution. Because %TASK 1 has the default 
priority of 7, which is higher than MOTHER’s priority, the main program 
resumes execution. 


@ At the third rendezvous with FATHER, FATHER raises the exception SOME_ 
ERROR on line 54. The handler on line 59 catches the exception, aborts 
the suspended CHILD task, and then reraises the exception. FATHER then 
terminates. 


@ A loop with a delay statement ensures that when control reaches line 103, 
FATHER has executed far enough to be terminated. 


@ This entry call ensures that MOTHER does not wait forever for its rendezvous 
on line 76. MOTHER executes the accept statement (which involves no other 
statements), the rendezvous is completed, and MOTHER is immediately 
switched off the processor at line 77 because its priority is only 6. 


® After its rendezvous with MOTHER, the main program (%TASK 1) executes 
lines 108 to 110. At line 110, the main program must wait for all its 
dependent tasks to terminate (see Section 12.6.4). When the main program 
reaches line 110, the only nonterminated task is MOTHER (which cannot 
terminate until the null statement at line 80 has executed). MOTHER finally 
executes to completion at line 81. Now that all tasks are terminated, the 
main program completes execution. The main program then returns and 
execution resumes with the VMS command-line interpreter. 


12.3 Specifying Tasks in Debugger Commands 


A task is an entity that executes in parallel with other tasks. A task is 
characterized by a unique task ID (defined in Section 12.3.3), a separate stack, 
and a separate register set. . 


The current definition of the active task and of the visible task determine the 
context for manipulating tasks. See Section 12.3.1. 


When specifying tasks in debugger commands, you can use any of the following 
forms: 


e A task (thread) name as declared in the program (for example FATHER 
in Section 12.2.2) or a language expression that yields a task value. 
Section 12.3.2 describes Ada language expressions for tasks. 


¢ A task ID (for example, %TASK 2). See Section 12.3.3. 
¢ A task built-in symbol (for example, %ACTIVE_TASK). See Section 12.3.4. 


12.3.1 Definition of Active Task and Visible Task 
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The active task is the task that runs when a STEP, GO, CALL, or EXIT 
command executes. Initially, it is the task in which execution is suspended when 
the debugger is invoked. To change the active task during a debugging session, 
use the SET TASK/ACTIVE command. For example, the following command 
makes the task named CHILD the active task: 


DBG> SET TASK/ACTIVE CHILD 
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The visible task is the task whose stack and register set are the current context 
that the debugger uses when looking up symbols, register values, routine calls, 
breakpoints, and so on. For example, the following command displays the value 
of the variable KEEP_COUNT in the context of the visible task: 


DBG> EXAMINE KEEP COUNT 


Initially, the visible task is the active task. To change the visible task, use the 
SET TASK/VISIBLE command. This enables you to look at the state of other 
tasks without affecting the active task. 


You can specify the active and visible tasks in debugger commands by using 
the built-in symbols %ACTIVE_TASK and %VISIBLE_TASK, respectively (see 
Section 12.3.4). 


See Section 12.5 for more information about using the SET TASK command to 
modify task characteristics. 


12.3.2 Ada Tasking Syntax 


You declare a task either by declaring a single task or by declaring an object of a 
task type. For example: 


-- TASK TYPE declaration. 


task type FATHER TYPE is 


end FATHER TYPE; 
task body FATHER TYPE is 


end FATHER TYPE; 
-- A single task. 


task MOTHER is 


end MOTHER; 
task body MOTHER is 


end MOTHER; 


A task object is a data item that contains a 32-bit task value. A task object 

is created when the program elaborates a single task or task object, when you 
declare a record or array containing a task component, or when a task allocator is 
evaluated. For example: | 


-- Task object declaration. 


FATHER : FATHER TYPE; 


-- Task object (T) as a component of a record. 


type SOME RECORD TYPE is 
record 
A, B: INTEGER; 
T +: FATHER TYPE; 
end record; 


HAS TASK : SOME RECORD TYPE; 
-- Task object (POINTER1) via allocator. 


type A is access FATHER TYPE; 
POINTER] : A := new FATHER TYPE; 
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A task object is comparable to any other object. You refer to a task object in 
debugger commands either by name or by path name. For example: 


DBG> EXAMINE FATHER 
DBG> EXAMINE FATHER TYPESTASK BODY.CHILD 


When a task object is elaborated, a task is created by the VAX Ada run-time 
library, and the task object is assigned its 32-bit task value. As with other Ada 
objects, the value of a task object is undefined before the object is initialized, and 
the results of using an uninitialized value are unpredictable. 


The task body of a task type or single task is implemented in VAX Ada as a 
procedure. This procedure is called by the VAX Ada run-time library when a task 
of that type is activated. A task body is treated by the debugger as a normal Ada 
procedure, except that it has a specially constructed name. 


To specify the task body in a debugger command, use the following syntax to refer 


to tasks declared as task types: 


task-type-identifier$TASK_BODY 
Use the following syntax to refer to single tasks: 
task-identifierS$TASK_BODY 


For example: 
DBG> SET BREAK FATHER TYPESTASK BODY 


The debugger does not support the task-specific Ada attributes T’7 CALLABLE, 
E’ COUNT, T’ STORAGE_ SIZE, and T’ TERMINATED, where T is a task type 
and E is a task entry (see the VAX Ada documentation for more information 
on these attributes). So you cannot enter commands such as EVALUATE 
CHILD’ CALLABLE. However, you can get the information provided by each 
of these attributes with the debugger SHOW TASK command. For more 
information, see Section 12.4. 


12.3.3 Task ID 
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A task ID is the number assigned to a task when it is created by the tasking 
system. The task ID uniquely identifies a task during the entire execution of a 
program. 


A task ID has the following syntax, where n is a positive decimal integer: 
%TASK n 


You can determine the task ID of a task object by evaluating or examining the 
task object. For example (Ada path-name syntax): 


DBG> EVALUATE FATHER 

STASK 2 

DBG> EXAMINE FATHER 

TASK _EXAMPLE.FATHER: ‘%TASK 2 


If the programming language does not have built-in tasking services, you must 
use the EXAMINE/TASK command to obtain the task ID of a task. 


Note that the EXAMINE/TASK/HEXADECIMAL command, when applied to a 
task object, yields the hexadecimal task value. The task value is the address of 
the task (or thread) control block of that task. For example (Ada example): 

DBG> EXAMINE/HEXADECIMAL FATHER 


TASK EXAMPLE.FATHER: 0015AD00 
DBG> 
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The SHOW TASK/ALL command enables you to identify the task IDs that have 
been assigned to all currently existing tasks. The following examples are derived 
from Example 12—1 and Example 12-2, respectively: 


DBG> SHOW TASK/ALL 


task id state hold pri. substate thread_object 
$TASK 1 READY HOLD 12 Initial thread 
* STASK 2 RUN 0 Null thread 
STASK 3 SUSP 12 Condition Wait THREAD EX1\main\threads[0].fieldl 
STASK 4 SUSP 12 Condition Wait THREAD _EX1\main\threads[1].fieldl 
DBG> 


DBG> SHOW TASK/ALL 
task id pri hold state  substate task object 


* STASK 1 7 RUN SHARESADARTL+130428 
STASK 2 7 SUSP Accept TASK_EXAMPLE,MOTHER+4 
STASK 4 7 SUSP Entry call TASK EXAMPLE.FATHER TYPE$TASK BODY.CHILD+4 
STASK 3 6 READY TASK EXAMPLE.MOTHER+4 

DBG> 


You can use task IDs to refer to nonexistent tasks in debugger conditional 
statements. For example, if you had already run your program once, and you 
discovered that %TASK 2 and 3 were of interest, you could enter the following 
commands at the beginning of your next debugging session before %TASK 2 or 3 
was created: 


DBG> SET BREAK %LINE 44 WHEN (%ACTIVE TASK=%TASK 3) 
DBG> IF (%CALLER=%TASK 3) THEN (SHOW TASK/FULL) 


In other words, you can use a task ID in certain debugger commands before the 
task has been created without the debugger reporting an error (as it would if you 
used a task object name before the task object came into existence). A task does 
not exist until the task is created. Later the task becomes nonexistent sometime 
after it terminates. A nonexistent task never appears in a debugger SHOW TASK 
display. 


Each time a program runs, the same task IDs are assigned to the same tasks 

so long as the program statements are executed in the same order. Different 
execution orders can result from ASTs (caused by delay statement expiration or 
input-output completion) being delivered in a different order. Different execution 
orders can also result from time slicing being enabled. A given task ID is never 
reassigned during the execution of the program. 


For all types of tasks, the run-time library always assigns %TASK 1 to the task 
that executes the main program. For DECthreads tasks, the run-time library 
always assigns %TASK 2 to the null task that executes when there are no other 
tasks—including the main program—eligible to execute. The null task is a special 
task created by the run-time library; you cannot apply most debugger commands 
to the null task. %TASK 0 refers to a nonexistent task (not the null task). 


12.3.4 Task Built-In Symbols 


The debugger built-in symbols defined in Table 12-2 enable you to specify tasks 
in command procedures and command constructs. 
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Table 12-2 Task Built-In Symbols 


Built-in Symbol Description 

%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or EXIT 
command executes. 

%CALLER_TASK (Applies only to Ada programs.) When an accept statement 


executes, the task that called the entry associated with the 
accept statement. 


%NEXT_TASK The task after the visible task in the debugger’s task list. The 
ordering of tasks is arbitrary but consistent within a single run 
of a program. 


%PREVIOUS_TASK The task previous to the visible task in the debugger’s task 
list. 
%VISIBLE_TASK The task whose call stack and register set are the current 


context for looking up symbols, register values, routine calls, 
breakpoints, and so on. 


Examples using these task built-in symbols follow. 


The following command obtains the task ID of the visible task: 
DBG> EVALUATE SVISIBLE TASK 


The following command places the active task on hold: 

DBG> SET TASK/HOLD SACTIVE TASK 

The following command sets a breakpoint on line 25 that triggers only when task 
CHILD executes that line: 

DBG> SET BREAK %LINE 25 WHEN (ACTIVE _TASK=CHILD) 

The symbols %NEXT_TASK and %PREVIOUS_TASK enable you to cycle through 
the total set of tasks that currently exist. For example: 


DBG> SHOW TASK %VISIBLE TASK; SET TASK/VISIBLE %NEXT_TASK 
DBG> SHOW TASK SVISIBLE TASK; SET TASK/VISIBLE %NEXT_ TASK 


DBG> EXAMINE MONITOR _TASK 
MOD\MONITOR_ TASK: %TASK 2 
DBG> WHILE *%NEXT_ TASK NEQ %ACTIVE DO (SET TASK *NEXT_TASK; SHOW CALLS) 


12.3.4.1 Caller Task Symbol (Ada) 
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The symbol %CALLER_TASK is specific to Ada tasks. It evaluates to the task ID 
of the task that called the entry associated with the accept statement. Otherwise, 
it evaluates to TASK 0. For example, %CALLER_TASK evaluates to ZTASK 0 
if the active task is not currently executing the sequence of statements associated 
with the accept statement. 


For example, suppose a breakpoint has been set on line 48 of Example 12-2 
(within an accept statement). The accept statement in this case is executed 

by task FATHER (“TASK 2) in response to a call of entry RENDEZVOUS by 
the main program (%TASK 1). Thus, when an EVALUATE %CALLER_TASK 
command is entered at this point, the result is the task ID of the calling task, the 
main program: 

DBG> EVALUATE %CALLER TASK 


sTASK 1 
DBG> 
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When the rendezvous is the result of an AST entry call, #CALLER_TASK 
evaluates to TASK 0 because the caller is not a task. 


12.4 Obtaining Information About Tasks 


To obtain information about one or more tasks of your program, use the SHOW 
TASK command. 


The SHOW TASK command displays information about existing (nonterminated) 
tasks. By default, the command displays one line of information about the visible 
task. 


Section 12.4.1 and Section 12.4.2 describe the information displayed by a SHOW 
TASK command for DECthreads and Ada tasks, respectively. 


12.4.1 Obtaining Information about DECthreads Tasks 


The command SHOW TASK/ALL displays information about all of the tasks of 
the program that currently exist (see Example 12-3). 


Example 12-3 Sample SHOW TASK/ALL Display for DECthreads Tasks 


1] Qe 13) ®o 9 6) 

task id state hold pri substate thread_object 
STASK 1 SUSP 12 Condition Wait Initial thread 
STASK 2 READY 0 Null thread 
$TASK 3 SUSP 12 Mutex Wait T_EXAMP\main\threads [0] .fieldl 
STASK 4 SUSP 12 Delay T EXAMP\main\threads[1].fieldl 
STASK 5 SUSP 12 Mutex Wait T EXAMP\main\threads[2].fieldl 

* STASK 6 RUN 12 T EXAMP\main\threads([3].fieldl 
sTASK 7 READY 12 T EXAMP\main\threads[4].field1 
STASK 8 SUSP 12 Mutex Wait T EXAMP\main\threads[5].fieldl 
STASK 9 READY 12 T EXAMP\main\threads[6].fieldl 
$TASK 10 TERM 12 Term. by alert T EXAMP\main\threads[7].fieldl 

DBG> 


Key to Example 12-3: 


@ The task ID (see Section 12.3.3). The active task is marked with an asterisk 
(*) in the leftmost column. 


@ The current state of the task (see Table 12-3). The task in the RUN 
(RUNNING) state is the active task. Table 12-3 lists the state transitions 
possible during program execution. 


Whether the task has been put on hold with a SET TASK/HOLD command, 
as explained in Section 12.5.1. 


The task priority. 


The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. See Table 12-4. 


A debugger path name for the task (thread) object or the address of the task 
object if the debugger cannot symbolize the task object. 


o @6 Oo 
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Table 12-3 Generic Task States 


Task State 
RUNNING 


READY 


SUSPENDED 


TERMINATED 


Description 


Task is currently running on the processor. This is the active task. A 
task in this state can make a transition to the READY, SUSPENDED, 
or TERMINATED state. 


Task is eligible to execute and waiting for the processor to be made 
available. A task in this state can make a transition only to the 
RUNNING state. 


Task is suspended—that is, waiting for an event rather than for the 
availability of the processor. For example, when a task is created, it 
remains in the suspended state until it is activated. A task in this 
state can make a transition only to the READY or TERMINATED 
state. 


Task is terminated. A task in this state cannot make a transition to 
another state. 


Table 12—4 DECthreads Task Substates 


Task Substate 


Condition Wait 
Delay 

Mutex Wait 

Not yet started 
Term. by alert 
Term. by exc 
Timed Cond Wait 


Description 


Task is waiting on a DECthreads condition variable. 

Task is waiting at a call to a DECthreads delay. 

Task is waiting on a DECthreads mutex. 

Task has not yet executed its start routine. 

Task has been terminated by an alert operation. 

Task has been terminated by an exception. 

Task is waiting on a timed DECthreads condition variable. 


The SHOW TASK/FULL command provides detailed information about each 
task selected for display. Example 12—4 shows the output of this command for a 
sample DECthreads task. 
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Example 12-4 Sample SHOW TASK/FULL Display for a DECthreads Task 


@ task id state hold pri substate thread object 

$TASK 4 SUSP 12 Delay T EXAMP\main\threads [1] .fieldl 
Alert is pending 
Alerts are deferred 


© Next pe: SHARESCMASRTL+4 6136 
Start routine: T EXAMP\thread_action 

0 Scheduling policy: throughput 

5) Stack storage: 
Bytes in use: 1288 © Base: 00334C00 
Bytes available: 40185 SP: 003346F8 
Reserved Bytes: 10752 Top: 00329A00 
Guard Bytes: 4095 

7) Thread control block: 
Size: 293 Address: 00311B78 

8) Total storage: 56613 

DBG> 


Key to Example 12-4: 

Identifying information about the task. 
Bulletin-type information about something unusual. 
Next execution PC value and start routine. 


Task scheduling policy. 


oo0o0 86 


Stack storage information: 

¢ Bytes in use:" the number of bytes of stack currently allocated. 

¢ "Bytes available:" the unused space in bytes. 

e "Reserved bytes: the storage allocated for handling stack overflow. 


¢ Guard bytes:" the size of the "guard area" or unwritable part of the 
stack. 


@ Minimum and maximum addresses of the task stack. 


@ Task (thread) control block information. The task value is the address, in 
hexadecimal notation, of the task control block. 


© The total storage used by the task. Adds together the task control block size, 
the number of reserved bytes, the top guard size, and the storage size. 


Figure 12-1 shows a task stack. 
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Figure 12—1 Diagram of a Task Stack 


low address 
pee guard (8 pages) 
reserved bytes (~21 pages) 
001EB600: ‘top 
address 
storage 
size 
001F2C38: ‘sp 
} bytes 
in use 
001FD2FC: ‘base 
address 
Nw 
00077D40: “d-task control block 
(490816) 
high address 
ZK-3333A-GE 


The SHOW TASK/STATISTICS command reports some statistics about all 

tasks in your program. Example 12—5 shows the output of the SHOW TASK 
/STATISTICS/FULL command for a sample program with DECthreads tasks. 
This information enables you to measure the performance of your program. The 
larger the number of total schedulings (also known as context switches), the more 
tasking overhead there is. 


Example 12-5 Sample SHOW TASK/STAT/FULL Display for DECthreads Tasks 
task statistics 

Total context switches: 0 

Number of existing threads: 0 

Total threads created: 0 
DBG> 
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12.4.2 Obtaining Task Information About Ada Tasks 


The SHOW TASK/ALL command displays information about all of the tasks 
of the program that currently exist—namely, tasks that have been created and 
whose master has not yet terminated (see Example 12-6). 


Example 12-6 Sample SHOW TASK/ALL Display for Ada Tasks 


1) ® 8 oO 5 ] 6) 

task id pri hold state  substate task object 

* STASK 1 7 RUN SHARESADARTL+130428 
STASK 2 7 HOLD SUSP Accept TASK EXAMPLE .MOTHER+4 
STASK 4 7 SUSP Entry call TASK EXAMPLE.FATHER_TYPE$TASK BODY.CHILD+4 
STASK 3 6 READY TASK_EXAMPLE . MOTHER) 

DBG> 


Key to Example 12-6: 


@ The task ID (see Section 12.3.3). The active task is marked with an asterisk 
(*) in the leftmost column. 


The task priority. Ada priorities range from 0 to 15. | 


2] 

© Whether the task has been put on hold with a SET TASK/HOLD command, 
as explained in Section 12.5.1. 

0 


The current state of the task (see Table 12-3). The task that is in the RUN 
(RUNNING) state is the active task. Table 12-3 lists the state transitions 
possible during program execution. 


The current substate of the task. The substate helps indicate the possible 
cause of a task’s state. See Table 12-5. 


© A debugger path name for the task object or the address of the task object if 
the debugger cannot symbolize the task object. 


® 


Table 12-5 Ada Task Substates 


Task Substate Description 

Abnormal Task has been aborted. 

Accept Task is waiting at an accept statement that is not inside a select 
statement. 

Activating Task is elaborating its declarative part. 

Activating tasks Task is waiting for tasks it has created to finish activating. 

Completed [abn] Task is completed due to an abort statement but is not yet 


terminated. In Ada, a completed task is one that is waiting 
for dependent tasks at its end statement. After the dependent 
tasks are terminated, the state changes to terminated. 


Completed [exc] Task is completed due to an unhandled exception! is not yet 
terminated. In Ada, a completed task is one that is waiting for 
dependent tasks at its end statement. After the dependent tasks 
are terminated, the state changes to terminated. 


1 An unhandled exception is one for which there is no handler in the current frame or for which there 
is a handler that executes a raise statement and propagates the exception to an outer scope. 


(continued on next page) 
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Table 12-5 (Cont.) Ada Task Substates 


Task Substate 
Completed 


Delay 
Dependents 
Dependents [exc] 


Entry call 
Invalid state 

1/O or AST 

Not yet activated 
Select or delay 


Select or terminate 
Select 


Shared resource 
Terminated [abn] 
Terminated [exc] 
Terminated 
Timed entry call 


Description 


Task is completed. No abort statement was issued and no 
unhandled exception’ occurred. 


Task is waiting at a delay statement. 
Task is waiting for dependent tasks to terminate. 


Task is waiting for dependent tasks to allow an unhandled 
exception! to propagate. 


Task is waiting for its entry call to be accepted. 

There is an error in the VAX Ada run-time library. 

Task is waiting for input-output completion or some AST. 
Task is waiting to be activated by the task that created it. 


Task is waiting at a select statement with a delay 
alternative. 


Task is waiting at a select statement with a terminate alternative. 


Task is waiting at a select statement with no else, delay, or 
terminate alternative. 


Task is waiting for an internal shared resource. 

Task was terminated by an abort statement. 

Task was terminated because of an unhandled exception.’ 
Task terminated normally. | 


Task is waiting in a timed entry call. 


1 An unhandled exception is one for which there is no handler in the current frame or for which there 
is a handler that executes a raise statement and propagates the exception to an outer scope. 


Figure 12-1 shows a task stack. For Ada tasks, the top guard is 10 pages, rather 


than 8. 


The SHOW TASK/FULL command provides detailed information about each 
task selected for display. Example 12—7 shows the output of this command for a 


sample Ada task. 


Example 12-7 Sample SHOW TASK/FULL Display for an ADA Task 


@ task id pri hold state  substate task object 
* STASK 2 RUN TASK _EXAMPLE.MOTHER+4 
2] Waiting entry callers: 


Waiters for entry BOGUS: 
STASK 4, type: CHILD 


(continued on next page) 
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Example 12-7 (Cont.) Sample SHOW TASK/FULL Display for an ADA Task 


13) Task type: FATHER TYPE 
Created at PC: TASK_EXAMPLE.%LINE 14+22 
Parent task: STASK 1 
Start PC: TASK_EXAMPLE.FATHER_TYPESTASK BODY 
0 Task control block: © stack storage (bytes): 
Task value: 490816 RESERVED BYTES: 10640 
Entries: 3 TOP GUARD SIZE: 5120 
Size: 1488 STORAGE SIZE: 30720 
6 Stack addresses: Bytes in use: ~ 456 
Top address: 001EB600 
Base address: 001F2DFC @ Total storage: 47968 
DBG> 


Key to Example 12-7: 


oo 


Identifying information about the task. 


Rendezvous information. If the task is a caller task, lists the entries for which 
it is queued. If the task is to be called, gives information about the kind of 
rendezvous that will take place and lists the callers that are currently queued 
for any of the task’s entries. 


Task context information. 


Task control block information. The task value is the address, in decimal | 
notation, of the task control block. 


Stack storage information: 


¢ RESERVED_BYTES gives the storage allocated by the Ada run-time 
library for handling stack overflow. 


¢ TOP_GUARD_SIZE gives the storage allocated for guard pages, which 
provide protection against storage overflow during task execution. You 
can specify the number of bytes to be allocated as guard pages with the 
VAX Ada pragmas TASK. STORAGE and MAIN_STORAGE; the number 
shown by the debugger is the number of bytes allocated (the pragma value 
is rounded up to an integral number of pages, as necessary). For more 
information about these pragmas and the top guard storage area, see the 
VAX Ada documentation. 


¢ STORAGE_SIZE gives the storage allocated for the task activation. You 
can specify the number of bytes to be allocated with the T’ STORAGE_ 
SIZE representation clause or in the VAX Ada pragma MAIN_STORAGE; 
the number shown by the debugger is the number of bytes allocated 
(the value specified is rounded up to an integral number of pages, as 
necessary). For more information about this representation clause and 
pragma and about the task activation (working) storage area, see the 
VAX Ada documentation. 


e «Bytes in use:" gives the number of bytes of stack currently allocated. 
Stack addresses of the task stack. 


The total storage used by the task. Adds together the task control block size, 
the number of reserved bytes, the top guard size, and the storage size. 
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The SHOW TASK/STATISTICS command reports some statistics about all 


_ tasks in your program. Example 12-8 shows the output of the SHOW TASK 


/STATISTICS/FULL command for a sample Ada tasking program. This 
information enables you to measure the performance of your program. The 
larger the number of total schedulings (also known as context switches), the more 
tasking overhead there is. 


Example 12-8 Sample SHOW TASK/STATISTICS/FULL Display for Ada Tasks 
task statistics . 


Entry calls = 4 Accepts = 1 Selects = 2 
Tasks activated = 3 Tasks terminated = 

ASTs delivered = 4 Hibernations = 0 
Total schedulings = 15 


Due to readying a higher priority task 
Due to task activations 

Due to suspended entry calls 

Due to suspended accepts 

Due to suspended selects 

Due to waiting for a DELAY 

Due to scope exit awaiting dependents 
Due to exception awaiting dependents 
Due to waiting for I/O to complete 

Due to delivery of an AST 

Due to task terminations 

Due to shared resource lock contention 


OPWHPDDDOON EF & Wp 


DBG> 


12.5 Changing Task Characteristics 
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To modify a task’s characteristics or the tasking environment while debugging, 
use the SET TASK command as shown in the following table. 


Command Description 

SET TASK/ACTIVE Makes a specified task the active task (see Section 12.3.1). 
SET TASK/VISIBLE Makes a specified task the visible task (see Section 12.3.1). 
SET TASK/ABORT Requests that a task be terminated at the next allowed 


opportunity. The exact effect depends on the current 
event facility (language dependent). For Ada tasks, this 
is equivalent to executing an abort statement. 


SET TASK/PRIORITY Sets a task’s priority. The exact effect depends on the current 
event facility (language dependent). 
SET TASK/RESTORE Restores a task’s priority. The exact effect depends on the 


current event facility (language dependent). 


SET TASK/[NOJHOLD Controls task switching (task state transitions, see 
Section 12.5.1). 


SET TASK/TIME_SLICE Controls the time slice value or disable time slicing (see 
Section 12.5.2). 


For more information about the SET TASK command and its qualifiers, see the 
command dictionary. 
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12.5.1 Putting Tasks on Hold to Control Task Switching 


Task switching might be confusing when you are debugging a program. Placing a 
task on hold with the SET TASK/HOLD command restricts the state transitions 
the task can make once the program is subsequently allowed to execute. 


A task placed on hold can enter any state except the RUNNING state. However, 
if necessary, you can force it into the RUNNING state by using the SET TASK 
/ACTIVE command. 


The SET TASK/HOLD/ALL command freezes the state of all tasks except the 
active task. You can use this command in combination with the SET TASK 
/ACTIVE command to observe the behavior of one or more specified tasks in 
isolation, by executing the active task with the STEP or GO command, and then 
switching execution to another task with the SET TASK/ACTIVE command. For 
example: . 


DBG> SET TASK/HOLD/ALL 
DBG> SET TASK/ACTIVE %STASK 1 
DBG> GO 


DBG> SET TASK/ACTIVE $TASK 3 
DBG> STEP 3 


When you no longer wish to have a task held, use the SET TASK/NOHOLD 
command. 


12.5.2 Debugging Programs That Use Time Slicing © 


Tasking programs that use time slicing are difficult to debug because time slicing 
makes the relative behavior of tasks asynchronous. Without time slicing, task 
execution is determined solely by task priority; task switches are predictable 

and the behavior of the program is repeatable from one run to the next. With 
time slicing, task priorities still govern task switches, but tasks of the same 
priority also take turns executing for a specified period of time. Thus, time slicing 
causes tasks to execute more independently from each other, and the behavior 

of a program that uses time slicing might not be repeatable from one run of the 
program to the next. 


The SET TASK/TIME_SLICE=t command enables you to specify a new time slice 
or disable time slicing (with SET TASK/TIME_SLICE=0.0). Thus, you can tune 
the execution of your tasking programs or diagnose problems that depend on the 
order in which tasks execute. 


Note that there is an interaction between time slicing and the debugger 
watchpoint implementation. When you set watchpoints, the debugger might 
automatically increase the value of the time-slice interval to 10.0 seconds. 
Slowing the time-slice rate prevents some problems. 
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12.6 Controlling and Monitoring Execution 


The following sections explain how to do the following functions: 


e Set task-specific and task-independent eventpoints (breakpoints, tracepoints, 
and so on) 


e Set breakpoints and tracepoints on DECthreads-specific task locations. 
¢ Set breakpoints and tracepoints on Ada-specific task locations. 


¢ Monitor task events with the SET BREAK/EVENT or SET TRACE/EVENT 
commands 


12.6.1 Setting Task-Specific and Task-Independent Debugger Eventpoints 
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An eventpoint is an event that you can use to return control to the debugger. 
Breakpoints, tracepoints, watchpoints, and the completion of STEP commands 
are eventpoints. 


A task-independent eventpoint can be triggered by the execution of any task 
in a program, regardless of which task is active when the eventpoint is set. Task- 
independent eventpoints are generally specified by an address expression such as 
a line number or a name. All watchpoints are task-independent eventpoints. The 
following are examples of setting task-independent eventpoints: 

DBG> SET BREAK COUNTER 


DBG> SET BREAK/NOSOURCE %LINE 42, CHILD$TASK BODY 
DBG> SET WATCH/AFTER=3 KEEP COUNT 


A task-specific eventpoint can be set only for the task that is active when 
the command is entered. A task-specific eventpoint is triggered only when that 
same task is active. For example, the STEP/LINE command is a task-specific 
eventpoint: other tasks might execute the same source line and not trigger the 
event. 


If you use the SET BREAK, SET TRACE, or STEP commands with the following 
qualifiers, the resulting eventpoints are task specific: 


AINSTRUCTION 

/LINE 

/RETURN 
/VECTOR_INSTRUCTION 


Any other eventpoints that you set with those commands and any eventpoints. 
that you set with the SET WATCH command are task independent. 
The following are examples of setting task-specific eventpoints: 


DBG> SET BREAK/ INSTRUCTION 
DBG> SET TRACE/INSTRUCTION/SILENT DO (EXAMINE KEEP COUNT) 
DBG> STEP/CALL/NOSOURCE 


You can conditionalize eventpoints that are normally task-independent to make 
them task specific. For example: 


DBG> SET BREAK %LINE 10 WHEN (%ACTIVE TASK=FATHER) 
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12.6.2 Setting Breakpoints on DECthreads Tasking Constructs 


You can set a breakpoint on a thread start routine. The breakpoint will trigger 
just before the start routine begins execution. In Example 12-1, this type of 
breakpoint would be set as follows: 


DBG> SET BREAK worker routine 


Unlike Ada tasks, you cannot specify the body of a DECthreads task by name but 
the start routine is similar. 


Specifying a WHEN clause with the SET BREAK command ensures that you 
catch the point at which a particular thread begins execution. For example: 


DBG> SET BREAK worker routine - 
_DBG> WHEN (SCALLER_TASK = $TASK 4) 


In Example 12-1, this conditional breakpoint would trigger when the second 
worker thread begins executing its start routine. 


Other useful places to set breakpoints are just prior to and immediately after 
condition waits, joins, and locking of mutexes. You can set such breakpoints by 
specifying either a line number or the routine name. 


12.6.3 Setting Breakpoints on Ada Task Bodies, Entry Calls, and Accept 
Statements 


You can set a breakpoint on a task body by using one of the following two forms 
to refer to the task body (see Section 12.3.2): 


task-type-identifierS$TASK_BODY 
task-identifierfSTASK_BODY 


For example, the following command sets a breakpoint on the body of task 
CHILD. This breakpoint is triggered just before the elaboration of the task’s 
declarative part (also called the task’s activation). 


DBG> SET BREAK CHILDSTASK BODY 


Note that CHILD$TASK_BODY is a name for the address of the first instruction 
the task will execute. It is meaningful to set a breakpoint on an instruction, 
and hence on this name. However, you must not name the task object (for 
example, CHILD) in a SET BREAK command. The task-object name designates 
the address of a data item (the 32-bit task value). Just as it is erroneous to set 
a breakpoint on an integer object, it is erroneous to set a breakpoint on a task 
object. 


You can monitor the execution of communicating tasks by setting breakpoints or 
tracepoints on entry calls and accept statements. 


Note 


Ada task entry calls are not the same as subprogram calls because task 
entry calls are queued and may not execute right away. If you use the 
STEP command to move execution into a task entry call, the results 
might not be what you expect. 


There are several points in and around an accept statement where you might 
want to set a breakpoint or tracepoint. For example, consider the following 
program segment, which has two accept statements for the same entry, 
RENDEZVOUS: 
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8 task body TWO ACCEPTS is 


9 begin 
10 for I in 1..2 loop 
11 select 
i2 accept RENDEZVOUS do 
13 PUT LINE("This is the first accept statement"); 
14 end RENDEZVOUS; 
15 or 
16 terminate; 
17 end select; 
18 end loop; 
19 accept RENDEZVOUS do 
20 PUT LINE("This is the second accept statement"); 
21 end RENDEZVOUS; 


22 end TWO ACCEPTS; 
You can set a breakpoint or tracepoint in the following places in this example: 


e At the start of an accept statement (line 12 or 19). By setting a breakpoint 
or tracepoint here, you can monitor when execution reaches the start of the | 
accept statement, where the accepting task might become suspended before a 
rendezvous actually occurs. 


e At the start of the body (sequence of statements) of an accept statement (line 
13 or 20). By setting a breakpoint or tracepoint here, you can monitor when 
a rendezvous has begun—that is, when the accept statement actually begins 
execution. 


e At the end of an accept statement (line 14 or 21). By setting a breakpoint or 
tracepoint here, you can monitor when the rendezvous has completed, and 
execution is about to switch back to the caller task. 


To set a breakpoint or tracepoint in and around an accept statement, you can 
specify the associated line number. For example, the following command sets a 
breakpoint on the start and also on the body of the first accept statement in the 
preceding example: 


DBG> SET BREAK SLINE 12, %LINE 13 


To set a breakpoint or a tracepoint on an accept statement body, you can also use 
the entry name (specifying its expanded name to identify the task body where the 
entry is declared). For example: 


DBG> SET BREAK TWO ACCEPTSSTASK BODY.RENDEZVOUS 


If there is more than one accept statement for an entry, the debugger treats the 
entry as an overloaded name. In other words, the debugger issues a message 
indicating that the symbol is overloaded, and you must use the SHOW SYMBOL 
command to identify the overloaded names that have been assigned by the 
debugger. For example: 

DBG> SHOW SYMBOL RENDEZVOUS 

overloaded symbol TEST. TWO_ACCEPTSSTASK BODY.RENDEZVOUS 


overloaded instance TEST. TWO _ACCEPTSSTASK_| BODY.RENDEZVOUS 1 
overloaded instance TEST. TWO  ACCEPTSSTASK | BODY.RENDEZVOUS __ ae, 


Overloaded names have an integer suffix preceded by two underscores. For more 
information on overloaded names, see Section E.1.15. 


To determine which of these overloaded names is associated with a particular 
accept statement, use the EXAMINE/SOURCE command. For example: 
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DBG> EXAMINE/ SOURCE TWO_ACCEPTSSTASK BODY.RENDEZVOUS 1 
module TEST ACCEPTS 


12: accept RENDEZVOUS do 
DBG> EXAMINE/SOURCE TWO ACCEPTSSTASK BODY.RENDEZVOUS 2 
module TEST ACCEPTS 


19: accept RENDEZVOUS do 


In the following example, when the breakpoint triggers, the caller task is 
evaluated (see Section 12.3.4 for information about the symbol %CALLER_TASK): 


DBG> SET BREAK TWO ACCEPTSS$TASK BODY.RENDEZVOUS 2 - 
_DBG> DO (EVALUATE SCALLER_ TASK) 


The following breakpoint triggers only when the caller task is %TASK 2: 


DBG> SET BREAK TWO _ACCEPTSSTASK_BODY.RENDEZVOUS 2 - 
_DBG> WHEN (%SCALLER TASK = %TASK 2) 


If the calling task has more than one entry call to the same accept statement, you 
can use the SHOW TASK/CALLS command to identify the source line where the 
entry call was issued. For example: 


DBG> SET BREAK TWO ACCEPTSSTASK BODY.RENDEZVOUS 2 7 
_DBG> DO (SHOW TASK/CALLS %CALLER_TASK) 
12.6.4 Monitoring Task Events 


The SET BREAK/EVENT and SET TRACE/EVENT commands enable you to 
set breakpoints and tracepoints that are triggered by task and exception events. 
For example, the following command sets tracepoints that trigger whenever task 
CHILD or %TASK 2 makes a transition to the RUN state: 


DBG> SET TRACE/EVENT=RUN CHILD, STASK 2 


When a breakpoint or tracepoint is triggered as a result of an event, the debugger 
identifies the event and gives additional information. 


The following tables list the event-name keywords that you can specify with the 
SET BREAK/EVENT and SET TRACE/EVENT commands: 


° Table 12-6 lists the generic language-independent events common to all 
tasks. 


¢ Table 12-7 lists the events specific to DECthreads tasks. 
° Table 12-8 lists the events specific to Ada tasks. 


Table 12-6 Generic Low-Level Task Scheduling Events 


Event Name Description 

RUN Triggers when a task is about to run. 

PREEMPTED Triggers when a task is being preempted from the RUN state and 
its state changes to READY. (See Table 12-3.) 

ACTIVATING Triggers when a task is about to begin its execution. 

SUSPENDED Triggers when a task is about to be suspended. 
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Table 12-7 DECthreads-Specific Events 


Event Name Description 

HANDLED Triggers when an exception is about to be handled in 
some TRY block. 

TERMINATED Triggers when a task is terminating (including by alert 

_ or exception). 

EXCEPTION_TERMINATED Triggers when a task is terminating because of an 
exception. 

FORCED_TERM Triggers when a task is terminating due to an alert 
operation. 


Table 12-8 Ada-Specific Events 


Event Name Description 

HANDLED Triggers when an exception is about to be handled 
in some Ada exception handler, including an others 
handler. 

HANDLED_OTHERS Triggers only when an exception is about to be handled 


in an others Ada exception handler. 


RENDEZVOUS_EXCEPTION Triggers when an exception begins to propagate out of 
a rendezvous. 


DEPENDENTS_EXCEPTION Triggers when an exception causes a task to wait for 
dependent tasks in some scope (includes unhandled 
exceptions,! which, in turn, include special exceptions 
internal to the VAX Ada run-time library; for more 
information, see the VAX Ada documentation). Often 
immediately precedes a deadlock. 


TERMINATED Triggers when a task is terminating, whether 
normally, by an abort statement, or by an exception. 

EXCEPTION_TERMINATED Triggers when a task is terminating due to an 
unhandled exception.1 

ABORT_TERMINATED Triggers when a task is terminating due to an abort 
statement. 


1 An unhandled exception is an exception for which there is no handler in the current frame or for 
which there is a handler that executes a raise statement and propagates the exception to an outer 
scope. 


In the previous tables, the exception-related events are included for completeness. 
Only the task events are discussed in the following paragraphs (for more 
information about the exception events, see Section E.1.10.3). 


You can abbreviate an event name keyword to the minimum number of characters 
that make it unique. 


The event-name keywords that you can specify with the SET BREAK/EVENT 

or SET TRACE/EVENT command depend on the current event facility, which 

is either THREADS or ADA in the case of task events. The appropriate event 
facility is set automatically when you invoke the debugger. The SHOW EVENT_ 
FACILITY command identifies the facility that is currently set and lists the valid 
event name keywords for that facility (including those for the generic events). 
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Several examples follow showing the use of the /EVENT qualifier. 


DBG> SET BREAK/EVENT=PREEMPTED 
DBG> GO 
break on THREADS event PREEMPTED 
Task STASK 4 is getting preempted by %TASK 3 


DBG> SET BREAK/EVENT=SUSPENDED 
DBG> GO 
break on THREADS event SUSPENDED 
Task sTASK 1 is about to be suspended 


DBG> SET BREAK/EVENT=TERMINATED 
DBG> GO 
break on THREADS event TERMINATED 
Task STASK 4 is terminating normally 
DBG> 


Certain predefined event breakpoints are set automatically when you invoke the 
debugger: 


¢ EXCEPTION_TERMINATED event breakpoints are predefined for programs 
that call DECthreads routines. 


¢ EXCEPTION_TERMINATED and DEPENDENTS_EXCEPTION event 
breakpoints are predefined for Ada programs or programs that call Ada 
routines. 


Ada examples of the predefined and other types of event breakpoints follow. 


Example of EXCEPTION_TERMINATED Event 


When the EXCEPTION_TERMINATED event is triggered, it usually indicates an 
unanticipated program error. For example: 


break on ADA event EXCEPTION TERMINATED 
Task STASK 2 is terminating because of an exception 
SADA-F-EXCCOP, Exception was copied at a "raise;" or "accept" 
-ADA-F-EXCEPTION, Exception SOME ERROR 
-ADA-F-EXCRAIPRI, Exception raised prior to PC = 00000B61 
DBG> 


Example of DEPENDENTS_ EXCEPTION Event (Ada) 


For Ada programs, the DEPENDENTS_EXCEPTION event often unexpectedly 
precedes a deadlock. For example: 


break on ADA event DEPENDENTS EXCEPTION 
Task *TASK 2 may await dependent tasks because of this exception: 
SADA-F-EXCCOP, Exception was copied at a "raise;" or "accept" 
~ADA-F-EXCEPTION, Exception SOME ERROR 
~ADA-F-EXCRAIPRI, Exception raised prior to PC = 00000B61 
DBG> 
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Example of RENDEZVOUS_EXCEPTION Event (Ada) 


For Ada programs, the RENDEZVOUS_EXCEPTION event enables you to see an 
exception before it leaves a rendezvous (before exception information has been 
lost due to copying the exception into the calling task). For example: 


break on ADA event RENDEZVOUS EXCEPTION 
Exception is propagating out of a rendezvous in task %TASK 2 
SADA-F~CONSTRAINT ERRO, CONSTRAINT ERROR 
~ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000BA6 
DBG> 


To cancel breakpoints (or tracepoints) set with the /EVENT qualifier, use the 
CANCEL BREAK/EVENT (or CANCEL TRACE/EVENT) command. Specify the 
event qualifier and optional task expression in the CANCEL command exactly as 
you did with the SET command, excluding any WHEN or DO clauses. 


You might want to set event breakpoints and tracepoints in a debugger 
initialization file for your tasking programs. For example: 


SET BREAK/EVENT=ACTIVATING 

SET BREAK/EVENT=HANDLED DO (SHOW CALLS) 

SET BREAK/EVENT=ABORT TERMINATED DO (SHOW CALLS) 
SET BREAK/EVENT=EXCEPTION TERM DO (SHOW CALLS) 
SET BREAK/EVENT=TERMINATED 


12.7 Additional Task-Debugging Topics 


The following sections discuss additional topics related to task debugging: 
° Deadlock 

¢ Automatic stack checking 

¢ Using Ctrl/Y 


12.7.1 Debugging Programs with Deadlock Conditions 
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A deadlock is an error condition in which each task in a group of tasks is 
suspended and no task in the group can resume execution until some other task 
in the group executes. Deadlock is a typical error in tasking programs (in much 
the same way that infinite loops are typical errors in programs that use WHILE 
statements). 


A deadlock is easy to detect: it causes your program to appear to suspend, or 
hang, in midexecution. When deadlock occurs in a program that is running under 
debugger control, press Ctrl/C to interrupt the deadlock and display the debugger 
prompt. 


In general, the SHOW TASK/ALL command (see Section 12.4) or the SHOW 
TASK/STATE=SUSPENDED command is useful because it shows which tasks 
are suspended in your program and why. The command SET TASK/VISIBLE 
%NEXT_TASK is particularly useful when debugging in screen mode. It enables 
you to cycle through all tasks and display the code that each task is executing, 
including the code in which execution is stopped. 


The SHOW TASK/FULL command gives detailed task state information, 
including information about rendezvous, entry calls, and entry index values. 
The SET BREAK/EVENT or SET TRACE/EVENT command (see Section 12.6.4) 
enables you to set breakpoints or tracepoints at or near locations that might lead 
to deadlock. The SET TASK/PRIORITY and SET TASK/RESTORE commands 
enable you to see if a low-priority task that never runs is causing the deadlock. 
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Table 12-9 lists a number of tasking deadlock conditions and suggests debugger 
commands that are useful in diagnosing the cause. 


Table 12-9 Ada Tasking Deadlock Conditions and Debugger Commands for 


Diagnosing Them 
Deadiock Condition 


Self-calling deadlock (a task calls 
one of its own entries) 


Circular-calling deadlock (a task 
calls another task, which calls the 
first task) 


Dynamic-calling deadlock (a 
circular series of entry calls exists, 
and at least one of the calls is a 
timed or conditional entry call in a 
loop) 


Exception-induced deadlock (an 
exception prevents a task from 
answering one of its entry calls, 
or the propagation of an exception 
must wait for dependent tasks) 


Deadlock due to incorrect run- 
time calculations for entry 
indexes, when conditions, and 
delay statements within select 
statements 


Deadlock due to entries being 
called in the wrong order 


Deadlock due to busy-waiting on 

a variable used as a flag that is to 
be set by a lower priority task, and 
the lower priority task never runs 
because a higher priority task is 
always ready to execute 


Debugger Commands 


SHOW TASK/ALL 
SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 


SHOW TASK/ALL 
SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 


SHOW TASK/ALL 
SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 


SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 

SHOW TASK/FULL 

SET BREAK/EVENT=DEPENDENTS_EXCEPTION 
(for Ada programs) 


SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 

EXAMINE 


SHOW TASK/ALL 
SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 


SHOW TASK/ALL 

SHOW TASK/STATE=SUSPENDED 
SHOW TASK/FULL 

SET TASK/PRIORITY 

SET TASK/RESTORE 


12.7.2 Automatic Stack Checking in the Debugger 


In tasking programs, an undetected stack overflow can occur in certain 
circumstances and can lead to unpredictable execution. (For more information on 
task stack overflow, see the Ada or DECthreads documentation.) The debugger 
automatically does the following stack checks to help you detect the source of 
stack overflow problems. (If the stack pointer is out of bounds, the debugger 


displays an error message.) 


e Astack check is done for the active task after a STEP command executes or 
a breakpoint triggers (see Section 12.6.1). (This check is not done if you have 
used the /SILENT qualifier with the STEP or SET BREAKPOINT command.) 


¢ A stack check is done for each task whose state is displayed in a SHOW 
TASK command. Thus, a SHOW TASK/ALL command automatically causes 
the stacks of all tasks to be checked. 
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The following examples show the kinds of error messages displayed by the 
debugger when a stack check fails. A warning is issued when most of the stack 
has been used up, even if the stack has not yet overflowed. 


warning: %STASK 2 has used up over 90% of its stack 
SP: 0011194C Stack top at: 00111200 Remaining bytes: 1868 


error: STASK 2 has overflowed its stack 
SP: QOO1QE93C Stack top at: 00111200 Remaining bytes: -10436 


error: %TASK 2 has underflowed its stack 
SP: 7FF363A4 Stack base at: 001189FC Stack top at: 00111200 


One of the unpredictable events that can happen after a stack overflows is that 
the stack can then underflow. This arises as follows. If a task stack overflows and 
the stack pointer remains in the top guard area, the VMS operating system will 
try to signal an ACCVIO condition. However, because the top guard area is not 

a writable area of the stack, the VMS operating system cannot write the signal 
arguments for the ACCVIO. When this happens, the VMS operating system cuts 
back the stack: it causes the frame pointer and stack pointer to point to the 
base of the main program stack area, writes the signal arguments, and then 
changes the program counter to force an image exit. If a time-slice AST or other 
AST occurs at this instant, execution can resume in a different task, and for a 
while, the program might continue to execute, although not normally (the task 
whose stack overflowed might use—and overwrite—the main program stack). The 
debugger stack checks help you to detect this situation. If you step into a task 
whose stack has been cut back by the VMS operating system, or if you use the 
SHOW TASK/ALL command at that time, the debugger issues its stack underflow 
message. 


12.7.3 Using Ctrl/Y When Debugging Ada Tasks 
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Pressing Ctrl/C is the recommended method of interrupting program execution 
or a debugger command during a debugging session. This returns control to the 
debugger, whereas pressing Ctrl/Y returns control to DCL level. 


If you interrupt a task debugging session by pressing Ctrl/Y, you might have 
some problems when you then invoke the debugger at DCL level with the 
DEBUG command. In such cases, you should insert the following two lines in 
the source code at the beginning of your main program to name the VAX Ada 
predefined package CONTROL_C_INTERCEPTION: 


with CONTROL C_ INTERCEPTION; 
pragma ELABORATE (CONTROL C INTERCEPTION) ; 


For information on this package, see the VAX Ada documentation. 
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The Debugger Command Dictionary contains detailed reference information about 
all debugger commands, organized as follows: 


¢ Section 1 explains how to enter debugger commands. 
¢ Section 2 gives general information about debugger diagnostic messages. 


¢ Section 3 lists commands that apply only when you are using the debugger at 
a workstation running VWS (not DECwindows). 


¢ Section 4 contains detailed reference information about the debugger 
commands. 


1 Debugger Command Format 


You can enter debugger commands interactively at the keyboard or store them 
within a command procedure to be invoked later with the @ (Execute Procedure) 
command, 


This section gives the following information: 
-® General format for debugger commands 
¢ Rules for entering commands interactively at the keyboard 


¢ Rules for entering commands in debugger command procedures 


1.1 General Format 


A command string is the complete specification of a debugger command. 
Although you can continue a command on more than one line, the term command 
string is used to define an entire command that is passed to the debugger. 


A debugger command string consists of a verb and, possibly, parameters and 
qualifiers. 


The verb specifies the command to be executed. Some debugger command strings 
might consist of only a verb or a verb pair. For example: 


DBG> GO 
DBG> SHOW IMAGE 


A parameter specifies what the verb acts on (for example, a file specification). 

A qualifier describes or modifies the action taken by the verb. Some command 
strings might include one or more parameters or qualifiers. In the following 
examples, COUNT, I, J, and K, OUT2, and PROG4.COM are parameters (@ is the 
"execute procedure" command); /SCROLL and /OUTPUT are qualifiers. 

DBG> SET WATCH COUNT 

DBG> EXAMINE I,J,K 


DBG> SELECT/SCROLL/OUTPUT OUT2 
DBG> @PROG4.COM 


Some commands accept optional WHEN or DO clauses. DO clauses are also used 
in some screen display definitions. 


A WHEN clause consists of the keyword WHEN followed by a conditional 
expression (within parentheses) that evaluates to true or false in the current 
language. A DO clause consists of the keyword DO followed by one or more 
command strings (within parentheses) that are to be executed in the order that 
they are listed. You must separate multiple command strings with semicolons (;). 
These points are illustrated in the next example. 
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The following command string sets a breakpoint on routine SWAP that is 
triggered whenever the value of J equals 4 during execution. When the 
breakpoint is triggered, the debugger executes the two command strings SHOW 
CALLS and EXAMINE LK, in the order indicated. 


DBG> SET BREAK SWAP WHEN (J = 4) DO (SHOW CALLS; EXAMINE I,K) 


The debugger checks the syntax of the commands in a DO clause when it executes 
the DO clause. You can nest commands within DO clauses. 


1.2 Entering Commands at the Keyboard 


When entering a debugger command interactively at the keyboard, you can 
abbreviate a keyword (verb, qualifier, parameter) to as few characters as are 
needed to make it unique within the set of all debugger keywords. However, some 
commonly used commands (for example, EXAMINE, DEPOSIT, GO, STEP) can be 
abbreviated to their first characters. Also, in some cases, the debugger interprets 
nonunique abbreviations correctly on the basis of context. | 


Pressing the Return key terminates the current line, causing the debugger to 
process it. To continue a long command string on another line, type a hyphen 
(-) before pressing Return. As a result, the debugger prompt is prefixed with an 
underscore character (_DBG>), indicating that the command string is still being 
accepted. 


You can enter more than one command string on one line by separating command 
strings with semicolons (;). 


To enter a comment (explanatory text that is recorded in a debugger log file 

but is otherwise ignored by the debugger), precede the comment text with an 
exclamation point (!). If the comment wraps to another line, start that line with 
an exclamation point. 


The command line editing functions that are available at the DCL prompt 

are also available at the debugger prompt, including command recall with the up 
arrow and down arrow keys. For example, pressing the left arrow and right arrow 
keys moves the cursor one character to the left and right, respectively; pressing 
Ctrl/H or Ctrl/E moves the cursor to the start or end of the line, respectively; 
pressing Ctrl/U deletes all the characters to the left of the cursor, and so on. 


To interrupt a command that is being processed by the debugger, press Ctrl/C. 
(See the description of Ctrl/C in the command dictionary.) 


1.3 Entering Commands in Command Procedures 
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To maximize legibility, it is best not to abbreviate command keywords in a 
command procedure. Do not abbreviate command keywords to less than four 
significant characters (not counting the negation /NO ... ), to avoid potential 
conflicts in future releases. 


Start a debugger command line at the left margin. (Do not start a command line 
with a dollar sign ($) as you do when writing a DCL command procedure). 


The beginning of a new line ends the previous command line (the end-of-file 
character also ends the previous command line). To continue a command string 
on another line, type a hyphen (-) before starting the new line. 


You can enter more than one command string on one line by separating command 
strings with semicolons (;). 
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To enter a comment (explanatory text that does not affect the execution of the 
command procedure), precede the comment text with an exclamation point (!). If 
the comment wraps to another line, start that line with an exclamation point. 


2 Debugger Diagnostic Messages 


The following example shows the elements of a debugger diagnostic message: 
‘SDEBUG-W-NOSYMBOL, symbol ‘X’ is not in the symbol table 
0 @e@ 4) 


3) 
DBG> 


@ The facility name (DEBUG). 
@ The severity level (W, in this example). 


© The message identifier (NOSYMBOL, in this example). The message 
identifier is an abbreviation of the message text. 


© The message text. 


The identifier enables you to find the explanation for a diagnostic message from 
the debugger’s online help (and the action you need to take, if any). 


To get online help about a debugger message, use the following general command 
format: 


HELP MESSAGES message-identifier 
The possible severity levels for diagnostic messages are as follows: 


S (success) 

I (informational) 

W (warning) 

E (error) 

F (fatal, or severe error) 


Success and informational messages inform you that the debugger has performed 
your request. 


Warning messages indicate that the debugger might have performed some, but 
not all, of your request and that you should verify the result. 


Error messages indicate that the debugger could not perform your request, but 
that the state of the debugging session was not changed. The only exceptions are 
if the message identifier was DBGERR or INTERR. These identifiers signify an 
internal debugger error, and you should submit a Software Performance Report 
(SPR) in such cases. 


Fatal messages indicate that the debugger could not perform your request and 
that the debugging session is in an indeterminate state from which you cannot 
recover reliably. Typically, the error ends the debugging session. 

3 Commands Recognized Only on Workstations Running VWS 


The following commands are recognized only when you are using the debugger at 
a workstation running VWS (not DECwindows): 


¢ SET MODE [NO]SEPARATE 
e SET PROMPT/(NO]POP 


See the descriptions of these commands in the command dictionary in Section 4. 
All of the other debugger commands apply to workstations as well as terminals. 
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4 Debugger Command Dictionary 


The Debugger Command Dictionary describes each of the debugger commands in 
detail. Commands are listed alphabetically. The following information is provided 
for each command: command description, format, parameters, qualifiers, and one 
or more examples. See the preface of this manual for documentation conventions. 
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@ (Execute Procedure) 


Format 


Parameters 


Description 


Executes a debugger command procedure. 


@file-spec [parameter(, .. . ]] 


file-spec 

Specifies the command procedure to be executed. For any part of the full 
file specification that is not provided, the debugger uses the file specification 
established with the last SET ATSIGN command, if any. If the missing part 
of the file specification was not established by a SET. ATSIGN command, the 
debugger assumes SYS$DISK:[ JDEBUG.COM as the default file specification. 
You can specify a logical name. 


parameter 

Specifies a parameter that is passed to the command procedure. The parameter 
can be an address expression, a value expression in the current language, or 

a debugger command; the command must be enclosed within quotation marks 
("). Unlike with DCL, you must separate parameters by commas. Also, you 
can pass aS many parameters as there are formal parameter declarations within 
the command procedure. For more information about passing parameters to 
command procedures, see the DECLARE command description. _ 


A debugger command procedure can contain any debugger commands, including 
another @ command. The debugger executes commands from the command 
procedure until it reaches an EXIT or QUIT command or the end of the file. At 
that point, the debugger returns control to the command stream that invoked 
the command procedure. A command stream can be the terminal, an outer 
(containing) command procedure, a DO clause in a command such as SET 
BREAK, or a DO clause in a screen display definition. 


By default, commands read from a command procedure are not echoed. If you 
enter the SET OUTPUT VERIFY command, all commands read from a command 
procedure are echoed on the current output device, as specified by DBG$OUTPUT 
(the default output device is SYS$OUTPUT). 


For information about passing parameters to command procedures, see the 
DECLARE command description. 


Related commands: 


DECLARE 

(SET,SHOW) ATSIGN 

SET OUTPUT [NO]VERIFY 
SHOW OUTPUT 
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DBG> SET ATSIGN USER: [JONES.DEBUG] .DBG 
DBG> SET OUTPUT VERIFY 
DBG> @CHECKOUT 

SDEBUG-I-VERIFYICF, entering command procedure CHECKOUT 
SET MODULE/ALL 

SET BREAK SUB1 

GO 
break at routine PROG5\SUB2 

EXAMINE X 
PROG5S\SUB2\X: 376 


SDEBUG-I-VERIFYICF, exiting command procedure MAIN 
DBG> 


In this example, the SET ATSIGN command establishes that debugger command 
procedures are, by default, in USER:[JONES.DEBUG] and have a file type 

of DBG. The @CHECKOUT command executes the command procedure 
USER:[JONES.DEBUG]JCHECKOUT.DBG. Commands contained within the 
command procedure are echoed because the SET OUTPUT VERIFY command 
was entered. 


ATTACH 


Format 


Parameters 


Description 


Examples 


Debugger Command Dictionary 
ATTACH 


Passes control of your terminal from the current process to another process. 
ATTACH process-name 


process-name 

Specifies the process to which your terminal is to be attached. The process 
must already exist before you try to attach to it. If the process name contains 
nonalphanumeric or space characters, you must enclose it in quotation marks 


Gm). 


The ATTACH command enables you to go back and forth between a debugging 
session and your command interpreter, or between two debugging sessions. To 
do so, you must first use the SPAWN command to create a subprocess (see the 
description of the SPAWN command); you can then attach to it whenever you 
want. To return to your original process with minimal system overhead, use 
another ATTACH command. 


Related command: SPAWN. 


1. DBG> SPAWN 
$ ATTACH JONES 
SDEBUG-I-RETURNED, control returned to process JONES 
DBG> ATTACH JONES 1 
$ 


In this example, the series of commands creates a subprocess named 
JONES_1 from the debugger (currently running in the process JONES) and 
then attaches to that subprocess. 


2. DBG> ATTACH "Alpha One" 
$ 


This example illustrates use of quotation marks to enclose a process name 
that contains a space character. 
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CALL 


CALL 


Format 


Parameters 
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Calls a routine that was linked with your program. 


CALL routine-name [(argumentf, .. . ])] 


routine-name 
Specifies the name or the memory address of the routine to be called. 


argument 


Specifies an argument that is required by the routine. Arguments can be passed 
by address (the default), by descriptor, by reference, and by value, as follows: 


%ADDR 


%DESCR 


%REF 


%VAL 


Passes the argument by address. This is the default. The format is 
as follows: 


CALL routine-name (%ADDR address-expression) 


The debugger evaluates the address expression and passes that 
address to the routine specified. For simple variables (such as X), 
the address of X is passed into the routine. This passing mechanism 
is how FORTRAN implements ROUTINE(X). In other words, for 
named variables, using %ADDR corresponds to a call by reference in 
FORTRAN. For other expressions, however, you must use the “REF 
function to call by reference. For complex or composite variables 
(such as arrays, records, and access types), the address is passed 
when you specify %ADDR, but the called routine might not handle 
the passed data properly. Do not specify a literal value (a number or 
an expression composed of numbers) when using ADDR. 


Passes the argument by descriptor. The format is as follows: 
CALL routine-name (%DESCR language-expression) 


The debugger evaluates the language expression and builds a VAX- 
standard descriptor to describe the value. The descriptor is then 
passed to the routine you named. You would use this technique to 
pass strings to a FORTRAN routine. 


Passes the argument by reference. The format is as follows: 
CALL routine-name (%REF language-expression) 


The debugger evaluates the language expression and passes 

a pointer to the value, into the called routine. This passing 
mechanism corresponds to the way FORTRAN passes the result 
of an expression. 


Passes the argument by value. The format is as follows: 
CALL routine-name (%VAL language-expression) 


The debugger evaluates the language expression and passes the 
value directly to the called routine. 


Qualifiers 


Debugger Command Dictionary 
CALL 


/AST (default) 

/NOAST 

Controls whether the delivery of asynchronous system traps (ASTs) is enabled or 
disabled during the execution of the called routine. The /AST qualifier specifies 
that ASTs can be delivered, if delivery of ASTs was enabled before the CALL 
command was entered (that is, unless you previously entered the DISABLE AST 
command). The /NOAST qualifier specifies that ASTs cannot be delivered. 


/SAVE_VECTOR_STATE 
/NOSAVE_VECTOR_STATE (default) 
Applies to vectorized programs. 


Controls whether the current state of the vector processor is saved and then 
restored when a routine is called with the CALL command. 


The state of the vector processor comprises the following: 


¢ The values of the vector registers (VO to V15) and the vector control registers 
(VCR, VLR, and VMR) 


e¢ Any vector exception (an exception caused by the execution of a vector 
instruction) that might be pending delivery 


When you use the CALL command to execute a routine, execution of the routine 
might change the state of the vector processor as follows: 


e By changing the values of vector registers or vector control registers 
¢ By causing a vector exception 


e By causing the delivery of a vector exception that was pending when the 
CALL command was issued 


The /SAVE_VECTOR_STATE qualifier specifies that after the called routine has 
completed execution, the debugger restores the state of the vector processor that 
exists before the CALL command is issued. This ensures that, after the called 
routine has completed execution: 


¢ Any vector exception that was pending delivery before the CALL command 
was issued is still pending delivery 


¢ No vector exception that was triggered during the routine call is still pending 
delivery 


¢ The values of the vector registers are identical to their values before the 
CALL command was issued 


The /NOSAVE_VECTOR_STATE qualifier, which is the default, specifies that the 
state of the vector processor that exists before the CALL command is issued is 
not restored by the debugger after the called routine has completed execution. In 
this case, the state of the vector processor after the routine call depends on the 
effect (if any) of the called routine. 


The /[NOJSAVE_VECTOR_STATE qualifiers have no effect on the VAX general 
registers. The values of these registers are always saved and restored when you 
execute a routine with the CALL command. 
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Description 
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The CALL command is one of the four debugger commands that can be used to 
execute your program (the others are GO, STEP, and EXIT). The CALL command 
enables you to execute a routine independently of the normal execution of your 
program. The CALL command executes a routine whether or not your program 
actually includes a call to that routine, as long as the routine was linked with 
your program. 


When you enter a CALL command, the debugger takes the following action. (See 
the qualifier descriptions for additional information.) 


1. Saves the current values of the VAX general registers. 
2. Constructs an argument list. 


3. Executes a call to the routine specified in the command and passes any 
arguments. 


Executes the routine. 


Displays the value returned by the routine in register RO. By VMS 
convention, after a called routine has executed, register RO contains the 
function return value (if the routine is a function) or the procedure completion 
status (if the routine is a procedure that returns a status value). If a called 
procedure does not return a status value or function value, the value in RO 
might be meaningless, and the "value returned" message can be ignored. 


6. Restores the values of the general registers to the values they had just before 
the CALL command was executed. 


7. Issues the prompt. 


The debugger assumes that the called routine conforms to the VMS procedure 
calling standard (see the VAX Architecture Handbook). However, the debugger 
does not know about all the argument-passing mechanisms for all supported 
languages. Therefore, you might need to specify how to pass parameters—for 
example, use CALL SUB1(%VAL X) rather than CALL SUB1(X). See your 
language documentation for complete information about how arguments are 
passed to routines. 


If you use the CALL command to call a routine that changes the value of a passed 
parameter and returns a new value, the returned value might be unreliable. 


A common debugging technique at an exception breakpoint (resulting from a SET 
BREAK/EXCEPTION or STEP/EXCEPTION command) is to call a dump routine 
with the CALL command. When you enter the CALL command at an exception 
breakpoint, any breakpoints, tracepoints, or watchpoints that were previously set 
within the called routine are disabled temporarily so that the debugger does not 
lose the exception context. However, such eventpoints are active if you enter the 
CALL command at a location other than an exception breakpoint. 


When an exception breakpoint is triggered, execution is suspended before any 
application-declared condition handler is invoked. At an exception breakpoint, 
entering a GO or STEP command after executing a routine with the CALL 
command causes the debugger to resignal the exception (see the descriptions of 
the GO and STEP commands). 


Examples 


Debugger Command Dictionary 
CALL 


If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
note the following additional points: 


The CALL command is executed in the context of the visible process, but 
images in any other processes that are not on hold (through a SET PROCESS 
/HOLD command) are also allowed to execute. If you use the DO command 
to broadcast a CALL command to one or more processes, the CALL command 
is executed in the context of each specified process that is not on hold, but 
images in any other processes that are not on hold are also allowed to execute. 
In all cases, a hold condition in the visible process is ignored. 


After execution is started, the way in which it continues depends on whether 
the SET MODE [NOJINTERRUPT command was entered. By default (SET 
MODE INTERRUPT), execution continues until it is suspended in any 
process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 


Related commands: 


GO 

EXIT 

DO 

SET PROCESS 

SET MODE [NO]JINTERRUPT 

SET VECTOR_MODE [NO]JSYNCHRONIZED 
STEP 

SYNCHRONIZE VECTOR_MODE 


DBG> CALL SUB1 (xX) 
value returned is 19 
DBG> 


This command calls the routine SUB1, passing the address of X as the 
required parameter (by default, the address of the argument specified is 
passed). The routine is a function whose returned value is 19. 


DBG> CALL SUB(%REF 1) 
value returned is 1 
DBG> 


This command passes a pointer to a memory location containing the numeric 
literal 1, into the routine SUB. 


DBG> SET MODULE SHARESLIBRTL 

DBG> CALL LIBSSHOW VM 

1785 calls to LIBSGET_VM, 284 calls to LIBS$FREE VM, 122216 bytes 
still allocated, value returned is 00000001 

DBG> 


This example shows how you could call the run-time library routine 
LIB$SHOW_VM (in the shareable image LIBRTL) to display memory 
statistics. The SET MODULE command makes the universal symbols 
(routine names) in LIBRTL visible in the main image. See the description of 
the /SHARE qualifier of the SHOW MODULE command for more information 
about this subject. 
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SUBROUTINE CHECK_TEMP (TEMPERATURE, ERROR MESSAGE) 
REAL TOLERANCE /4.7/ ° 
REAL TARGET TEMP /92.0/ 
CHARACTER* (*) ERROR MESSAGE 


IF (TEMPERATURE .GT. (TARGET TEMP + TOLERANCE)) THEN 
TYPE *,’Input temperature out of range:’, TEMPERATURE 
TYPE *,ERROR MESSAGE 
ELSE 
TYPE *,’Input temperature in range:’ , TEMPERATURE 
END IF 
RETURN 
END 


DBG> CALL CHECK TEMP (%REF 100.0, %DESCR ‘’TOLERANCE-CHECK 1 FAILED’) 
Input temperature out of range: 100.0000 

TOLERANCE-CHECK 1 FAILED 

value returned is 0 

DBG> CALL CHECK TEMP(%SREF 95.2, SDESCR 'TOLERANCE-CHECK. 2 FAILED’ ) 
Input temperature in range: 95.2000 

value returned is 0 

DBG> 


In this example, the source code is that of a FORTRAN routine (CHECK_ 
TEMP) that accepts two parameters, TEMPERATURE (a real number) and 
ERROR_MESSAGE (a string). Depending on the value of the temperature, 
the routine prints different output. Each of the two CALL commands passes 
a temperature value (by reference) and an error message (by descriptor). 
Because this routine does not have a formal return value, the value returned 
is undefined, in this case, 0. 


Debugger Command Dictionary 
CANCEL ALL 


CANCEL ALL 


Format 


Qualifiers 


Description 


Cancels all breakpoints, tracepoints, and watchpoints. Restores the scope and 
type to their default values. Restores the line, symbolic, and G_Float modes 
established with the SET MODE command to their default values. 


CANCEL ALL 


/PREDEFINED 
Cancels all predefined (but no user defined) breakpoints, tracepoints, and 
watchpoints. 


/USER 

Cancels all user defined (but no predefined) breakpoints, tracepoints, and 
watchpoints. CANCEL ALL/USER is assumed by default unless you specify 
/PREDEFINED. 


The CANCEL ALL command performs the followings steps: 


¢ Cancels all breakpoints, tracepoints, and watchpoints. This is equivalent to 
entering the CANCEL BREAK/ALL, CANCEL TRACE/ALL, and CANCEL 
WATCH/ALL commands. Depending on the type of program (for example 
Ada, multiprocess), certain predefined breakpoints or tracepoints might 
be set automatically when you invoke the debugger. By default (CANCEL 
ALL/USER), only user defined breakpoints, tracepoints, and watchpoints are 
canceled—those that were previously set explicitly with the SET BREAK, 
SET TRACE, and SET WATCH commands. If you specify /PREDEFINED but 
not /USER, all predefined (but no user defined) breakpoints, tracepoints, and 
watchpoints are canceled. If you specify both /PREDEFINED and /USER, all 
predefined and user defined breakpoints, tracepoints, and watchpoints are 
canceled. 


See Section 9.3.2 for information about predefined breakpoints associated 
with Ada tasking exception events. See Chapter 10 for information about 
predefined tracepoints associated with multiprocess programs. 


¢ Restores the scope search list to its default value (0,1,2, ...,n). This is 
equivalent to entering the CANCEL SCOPE command. 


¢ Restores the data type for memory locations that are associated with a 
compiler generated type to the associated type. Restores the type for locations 
that are not associated with a compiler generated type to "longword integer". 
This is equivalent to entering the CANCEL TYPE/OVERRIDE and SET 
TYPE LONGWORD commands. 


¢ Restores the line, symbolic, and G_Float modes established with the SET 
MODE command to their default values. This is equivalent to entering the 
following command: 


DBG> SET MODE LINE, SYMBOLIC,NOG FLOAT 
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Examples 
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The CANCEL ALL command does not affect the current language setting or 
modules included in the run-time symbol table. 


Related commands: 


CANCEL BREAK 

CANCEL TRACE 

CANCEL TYPE/OVERRIDE 
CANCEL SCOPE 

CANCEL WATCH 
(SET,CANCEL) MODE 

SET TYPE 


DBG> CANCEL ALL 


This command cancels all user defined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. In this example, there are no predefined breakpoints, tracepoints, or 
watchpoints. 


DBG> CANCEL ALL 
SDEBUG-I-PREDEPTNOT, predefined eventpoint(s) not canceled 
DBG> 


This command cancels all user defined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. In this example, there are some predefined breakpoints, tracepoints, 
or watchpoints, and these are not canceled by default. 


DBG> CANCEL ALL/PREDEFINED 


This command cancels all predefined breakpoints, tracepoints, and 
watchpoints and restores scopes, types, and some modes to their default 
values. No user defined breakpoints, tracepoints, or watchpoints are affected. 


Debugger Command Dictionary 
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CANCEL BREAK 


Format 


Parameters 


Qualifiers 


Cancels a breakpoint. 


CANCEL BREAK [address-expression[, .. . ]] 


address-expression 

Specifies a breakpoint to be canceled. Do not use the asterisk (*) wildcard 
character. Instead, use the /ALL qualifier. Do not specify an address expression 
when using any of the qualifiers except for /EVENT, /PREDEFINED, or /USER. 


/ACTIVATING 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


Cancels the effect of a previous SET BREAK/ACTIVATING command. Do not 
specify an address expression with /ACTIVATING. 


/ALL 

By default, cancels all user-defined breakpoints. When used with /PREDEFINED, 
cancels all predefined breakpoints but no user-defined breakpoints. Specify both 
/USER and /PREDEFINED to cancel all breakpoints. Do not specify an address 
expression with /ALL. 


/BRANCH 
Cancels the effect of a previous SET BREAK/BRANCH command. Do not specify 
an address expression with /BRANCH. 


/CALL 
Cancels the effect of a previous SET BREAK/CALL command. Do not specify an 
address expression with /CALL. 


/EVENT=event-name 

Cancels the effect of a previous SET BREAK/EVENT=event-name command. 
Specify the event name (and address expression, if any) exactly as it was specified 
with the SET BREAK/EVENT command. 


To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 


/EXCEPTION 
Cancels the effect of a previous SET BREAK/EXCEPTION command. Do not 
specify an address expression with /EXCEPTION. 


/INSTRUCTION 
Cancels the effect of a previous SET BREAK/INSTRUCTION command. Do not 
specify an address expression with /INSTRUCTION. 
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/LINE 
Cancels the effect of a previous SET BREAK/LINE command. Do not specify an 
address expression with /LINE. 


/PREDEFINED 
Cancels a specified predefined breakpoint without affecting any user defined 
breakpoints. When used with /ALL, cancels all predefined breakpoints. 


/TERMINATING 
Cancels the effect of a previous SET BREAK/TERMINATING command. Do not 
specify an address expression with /TERMINATING. 


/USER 

Cancels a specified user-defined breakpoint without affecting any predefined 
breakpoints. When used with /ALL, cancels all user defined breakpoints. 
CANCEL BREAK/USER is assumed by default unless you specify 
/PREDEFINED. 


/VECTOR_INSTRUCTION 
Cancels the effect of a previous SET BREAK/VECTOR_INSTRUCTION command. 
Do not specify an address expression with /VECTOR_INSTRUCTION. 


Breakpoints can be user defined or predefined. User defined breakpoints are 
those that you set explicitly with the SET BREAK command. Predefined 
breakpoints, which depend on the type of program you are debugging (for 
example, Ada or multiprocess), are established automatically when you invoke 
the debugger. Use the SHOW BREAK command to identify all breakpoints that 
are currently set. Any predefined breakpoints are identified as such. 


User-defined and predefined breakpoints are set and canceled independently. 
For example, a location or event can have both a user defined and a predefined 
breakpoint. Canceling the user defined breakpoint does not affect the predefined 
breakpoint, and conversely. 


To cancel only user defined breakpoints, do not specify /PREDEFINED with the 
CANCEL BREAK command (/USER is the default). To cancel only predefined 
breakpoints, specify (PREDEFINED but not /USER. To cancel both user defined 
and predefined breakpoints, specify both /USER and /PREDEFINED. 


In general, the effect of the CANCEL BREAK command is symmetrical with 
that of the SET BREAK command (even though the SET BREAK command 

is used only with user defined breakpoints). Thus, to cancel a breakpoint 
that was established at a specific location, specify that same location (address 
expression) with the CANCEL BREAK command. To cancel breakpoints that 
were established on a class of instructions or events, specify the class of 
instructions or events with the corresponding qualifier (for example, /LINE, 
/BRANCH, /ACTIVATING, /EVENT=, and so on). See the qualifier descriptions 
for more specific information. 


Related commands: 


CANCEL ALL 

(SET,SSHOW) BREAK 
(SET,SSHOW) EVENT_FACILITY 
(SET,SHOW,CANCEL) TRACE 


Examples 


Debugger Command Dictionary 
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DBG> CANCEL BREAK MAIN\LOOP+10 

This command cancels the user defined breakpoint set at the address 
expression MAIN\ LOOP+10. 

DBG> CANCEL BREAK/ALL 


This command cancels all user defined breakpoints. 


DBG> CANCEL BREAK/ALL/USER/PREDEFINED 


This command cancels all user defined and predefined breakpoints. 


DBG_1> CANCEL BREAK/ACTIVATING 


This command cancels a previous user defined SET BREAK/ACTIVATING 
command. As a result, the debugger does not suspend execution when a new 
process is brought under debugger control. 


DBG> CANCEL BREAK/EVENT=EXCEPTION_TERMINATED/PREDEF INED 


This command cancels the predefined breakpoint that is set on task 
terminations due to unhandled exceptions. This breakpoint is predefined 
for Ada programs and programs that call Ada or DECthreads routines. 
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CANCEL DISPLAY 


Format 


Parameters 


Qualifiers 


Description 
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Permanently deletes a screen display. 


CANCEL DISPLAY [display-namel, . .. ]] 


display-name 

Specifies the name of a display to be canceled. Do not specify the PROMPT 
display, which cannot be canceled. Do not use the asterisk (*) wildcard character. 
Instead, use the /ALL qualifier. Do not specify a display name with /ALL. 


/ALL 
Cancels all displays, except for the PROMPT display. Do not specify a display 
name with /ALL. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


When. a display is canceled, its contents are permanently lost, it is deleted from 
the display list, and all the memory that was allocated to it is released. 


You cannot cancel the PROMPT display. 
Related commands: 


(SET,SSHOW) DISPLAY 
(SET,SSHOW,CANCEL) WINDOW 


Debugger Command Dictionary 
CANCEL DISPLAY 


Examples 
1. DBG> CANCEL DISPLAY SRC2 


This command permanently deletes display SRC2. 


2. DBG> CANCEL DISPLAY/ALL 


This command permanently deletes all displays, except for the PROMPT 
display. 
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CANCEL IMAGE 


Format 


Parameters 


Qualifiers 


Description 


Example 
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Deletes symbol table information for a shareable image. 


CANCEL IMAGE [image-namef[, .. . ]] 


image-name 

Specifies a previously set shareable image to be canceled. Do not specify the main 
image, which cannot be canceled. Do not use the asterisk (*) wildcard character. 
Instead, use the /ALL qualifier. Do not specify an image name with /ALL. 


/ALL 
Specifies that all shareable images except the main image are to be canceled. Do 
not specify an image name with /ALL. 


The CANCEL IMAGE command deallocates the data structures previously built 
to debug a shareable image by a SET IMAGE command. Use the CANCEL 
IMAGE command if the debugger performance has slowed down because of 
many images and modules being set. You can also use the CANCEL MODULE 
command to delete only certain modules from an image’s run-time symbol table 
(RST) without canceling the entire image. Also, if dynamic mode is enabled (this 
is the default), you can disable it with the SET MODE NODYNAMIC command. 
As a result, the debugger does not set images or modules automatically. 


If the current image (the image last set with the SET IMAGE command) is 
canceled, the main image (the image containing the image transfer address) 
becomes the current image. 


Related commands: 


(SET,SHOW) IMAGE 
SET MODE [NO]DYNAMIC 
(SET,SSHOW,CANCEL) MODULE 


DBG> CANCEL IMAGE SHARE2, SHARE3 
This command cancels shareable images SHARE2 and SHARES. If either of 


these was the current image, the main image becomes the current image. 
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CANCEL MODE 


CANCEL MODE 


Format 


Description 


Example 


Restores the line, symbolic, and G_float modes established by the SET MODE 
command to their default values. Also restores the default input/output radix. 


CANCEL MODE 


The effect of the CANCEL MODE command is equivalent to the following 
commands: 


DBG> SET MODE LINE, SYMBOLIC,NOG FLOAT 
DBG> CANCEL RADIX 


Although the same default modes apply to all languages, the default radix for 
both data entry and display is decimal for all languages except BLISS and 
MACRO. It is hexadecimal for BLISS and MACRO. 


Related commands: 


(SET,SHOW) MODE 
(SET,SHOW,CANCEL) RADIX 


DBG> CANCEL MODE 


This command restores the default radix mode and all default mode values. 
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CANCEL MODULE 


Format 


Parameters 


Qualifiers 


Description 
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Deletes the symbol records of a module in the current image from the run-time 
symbol table (RST) for that image. 


CANCEL MODULE [module-name{, ... ]] 


module-name ; 

Specifies the name of a module whose symbol records are deleted from the RST. 
Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. 
Do not specify a module name with /ALL. 


/ALL 
Deletes the symbol records of all modules from the RST. Do not specify a module 
name or /[NOJRELATED with /ALL. 


/RELATED (default) 
/NORELATED 
Applies to Ada programs. 


Controls whether the debugger deletes from the RST the symbol records of a 
module that is related to a specified module through a with-clause or subunit 
relationship. 


CANCEL MODULE/RELATED deletes symbol records for related modules as 
well as for those specified, but not for any module that is also related to another 
set module. The effect of CANCEL MODULE/RELATED is consistent with 
Ada’s scope and visibility rules and depends on the actual relationship between 
modules. CANCEL MODULE/NORELATED deletes symbol records only for 
modules that are specified (no symbol records are deleted for related modules). 


Note 


The current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 


Use the CANCEL MODULE command if the debugger performance has slowed 
down because of many modules being set. You can also use the CANCEL IMAGE 
command to delete the symbols of an entire image (this automatically cancels 
all of the modules in that image). Also, if dynamic mode is enabled (this is the 
default), you can disable it with the SET MODE NODYNAMIC command. As a 
result, the debugger does not set modules or images automatically. 


The CANCEL MODULE command does not cancel any breakpoints, tracepoints, 
or watchpoints that are set currently. It deletes the symbolization of any 
breakpoints, tracepoints, or watchpoints associated with the canceled modules. 


Debugger Command Dictionary 
CANCEL MODULE 


See Section E.1.14 for information specific to Ada programs. 
Related commands: 


(SET,SHOW,CANCEL) IMAGE 
SET MODE [NO]DYNAMIC 
(SET,SSHOW) MODULE 


Examples 
1. DBG> CANCEL MODULE SUB1 
This command deletes the symbols of module SUB1 from the RST. 


2. DBG> CANCEL MODULE/ALL 


This command deletes the symbols of all modules from the RST. 
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CANCEL RADIX 


CANCEL RADIX 


Format 


Qualifiers 


Description 


Examples 
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Restores the default radix for the entry and display of integer data. 
CANCEL RADIX 


/OVERRIDE 

Cancels the override radix established by a previous SET RADIX/OVERRIDE 
command. This sets the current override radix to "none" and restores the output 
radix mode to the value established with a previous SET RADIX or SET RADIX 
/OUTPUT command. If you did not change the radix mode with a SET RADIX 
or SET RADIX/OUTPUT command, the CANCEL RADIX/OVERRIDE command 
restores the radix mode to its default value (decimal for all languages except 
BLISS and MACRO, hexadecimal for BLISS and MACRO). 


The CANCEL RADIX command cancels the effect of any previous SET RADIX 
and SET RADIX/OVERRIDE commands. It restores the input and output radix 
to their default value (decimal for all languages except BLISS and MACRO, 
hexadecimal for BLISS and MACRO). 


The effect of the CANCEL RADIX/OVERRIDE command is more limited and is 
explained in the description of the /OVERRIDE qualifier. 


Related commands: 


EVALUATE 
(SET,SHOW) RADIX 


1, DBG> CANCEL RADIX 


This command restores the default input and output radix. 


2. DBG> CANCEL RADIX/OVERRIDE 


This command cancels any override radix you might have set with the SET 
RADIX/OVERRIDE command. 
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CANCEL SCOPE 


Format 


Description 


Example 


Restores the default scope search list for symbol lookup. 


CANCEL SCOPE 


The CANCEL SCOPE command cancels the current scope search list established 
by a previous SET SCOPE command and restores the default scope search list, 
namely 0,1,2, ...,n, where n is the number of calls in the call stack. 


The default scope search list specifies that, for a symbol without a pathname 
prefix, a symbol lookup such as "EXAMINE X" first looks for X in the routine 
that is currently executing (scope 0); if no X is visible there, the debugger looks in 
the caller of that routine (scope 1), and so on down the call stack; if X is not found 
in scope n, the debugger searches the rest of the run-time symbol table (RST), 
then searches the global symbol table (GST), if necessary. 


Related commands: (SET,SSHOW) SCOPE. 


DBG> CANCEL SCOPE 


This command cancels the current scope. 
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CANCEL SOURCE 


Format 


Qualifiers 


Description 
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Cancels a source directory search list established by a previous SET SOURCE 
command. 


CANCEL SOURCE 


/EDIT 
Applies mainly to Ada programs. 


Cancels the effect of a previous SET SOURCE/EDIT command. As a result, when 
you use the EDIT command, the debugger searches for a source file in the same 
directory that it was in at compile time. The CANCEL SOURCE/EDIT command 
does not cancel the effect of a previous SET SOURCE command. 


/MODULE=module-name 

Cancels the effect of a previous SET SOURCE/MODULE=module-name command 
in which the same module name was specified. (The module-name specifies a 
module for which a source directory search list is canceled.) As a result, the 
debugger searches for the source file of the specified module in the same directory 
that it was in at compile time. The CANCEL SOURCE/MODULE=module-name 
command does not cancel the effect of a previous SET SOURCE command, or of 
a SET SOURCE/MODULE=module-name command in which a different module 
name was specified. 


When used without a qualifier, the CANCEL SOURCE command cancels the 
effect of a previous SET SOURCE command used without a qualifier. CANCEL 
SOURCE does not cancel the effect of a previous SET SOURCE/EDIT or SET 
SOURCE/MODULE=module-name commands. 


See the qualifier descriptions for an explanation of their effects. 


The /EDIT qualifier is needed when the files used for the display of source code 
are different from the files to be edited by means of the EDIT command. This 

is the case with Ada programs. For Ada programs, the (SET,SSHOW,CANCEL) 
SOURCE commands affect the search of files used for source display (the "copied" 
source files in Ada program libraries); the (SET,SSHOW,CANCEL) SOURCE/EDIT 
commands affect the search of the source files that you edit when using the 
EDIT command. If you use /(MODULE with /EDIT, the effect of /EDIT is further 
qualified by (MODULE. 


See Section E.1.5 and Section E.1.6 for information specific to Ada programs. 
Related commands: 


(SET,SSHOW) MAX_SOURCE_FILES 
(SET,SHOW) SOURCE 


Example 
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DBG> SHOW SOURCE 
source directory search list for COBOLTEST: 


SYSTEM: : DEVICE: [PROJD] 
source directory search list for all other modules: 
[PROJA] 
[PROJB] 
[PETER.PROJC] 
DBG> CANCEL SOURCE 
DBG> SHOW SOURCE 
source directory search list for COBOLTEST: 
] 


SYSTEM: : DEVICE: [PROJD] 
DBG> CANCEL SOURCE/MODULE=COBOLTEST 
DBG> SHOW SOURCE 
no directory search list in effect 
DBG> 


In this example, the CANCEL SOURCE command cancels the effect of a previous 
SET SOURCE command. It does not cancel any source directory search lists for 
specific modules. But the CANCEL SOURCE/MODULE=module-name command 
(in this case, COBOLTEST) cancels the source directory search list for that 
module. 
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CANCEL TRACE 


CANCEL TRACE 


Format 


Parameters 


Qualifiers 
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Cancels a tracepoint. 
CANCEL TRACE [address-expression[, ... ]] 


address-expression 

Specifies a tracepoint to be canceled. Do not use the asterisk (*) wildcard 
character. Instead, use the /ALL qualifier. Do not specify an address expression 
when using any of the qualifiers except for /EVENT, /PREDEFINED, or /USER. 


/ACTIVATING 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


Cancels the effect of a previous SET TRACE/ACTIVATING command. Do not 
specify an address expression with /ACTIVATING. 


/ALL 

By default, cancels all user defined tracepoints. When used with /PREDEFINED, 
cancels all predefined tracepoints but no user defined tracepoints. Specify both 
/USER and /PREDEFINED to cancel all tracepoints. Do not specify an address 
expression with /ALL. | 


/BRANCH . 
Cancels the effect of a previous SET TRACE/BRANCH command. Do not specify 
an address expression with /BRANCH. 


ICALL 
Cancels the effect of a previous SET TRACE/CALL command. Do not specify an 
address expression with /CALL. 


/EVENT=event-name 

Cancels the effect of a previous SET TRACE/EVENT=event-name command. 
Specify the event name (and address expression, if any) exactly as they were 
specified with the SET TRACE/EVENT command. 


To identify the current event facility and the associated event names, use the 
SHOW EVENT_FACILITY command. 


/EXCEPTION 
Cancels the effect of a previous SET TRACE/EXCEPTION command. Do not 
specify an address expression with /EXCEPTION. 


ANSTRUCTION 
Cancels the effect of a previous SET TRACE/INSTRUCTION command. Do not 
specify an address expression with /INSTRUCTION. 


Description 


Debugger Command Dictionary 
CANCEL TRACE 


/LINE 
Cancels the effect of a previous SET TRACE/LINE command. Do not specify an 
address expression with /LINE. 


/PREDEFINED 
Cancels a specified predefined tracepoint without affecting any user defined 
tracepoints. When used with /ALL, cancels all predefined tracepoints. 


‘TERMINATING 
Cancels the effect of a previous SET TRACE/TERMINATING command. Do not 
specify an address expression with /TERMINATING. 


/USER 

Cancels a specified user defined tracepoint without affecting any predefined 
tracepoints. When used with /ALL, cancels all user defined tracepoints. CANCEL 
BREAK/USER is assumed by default unless you specify /PREDEFINED. 


/VECTOR_INSTRUCTION 
Cancels the effect of a previous SET TRACE/VECTOR_INSTRUCTION command. 
Do not specify an address expression with /VECTOR_INSTRUCTION. 


Tracepoints can be user defined or predefined. User defined tracepoints are those 
that you set explicitly with the SET TRACE command. Predefined tracepoints, 
which depend on the type of program you are debugging (for example, Ada or 
multiprocess), are established automatically when you invoke the debugger. Use 
the SHOW TRACE command to identify all tracepoints that are currently set. 
Any predefined tracepoints are identified as such. 


User defined and predefined tracepoints are set and canceled independently. 
For example, a location or event can have both a user defined and a predefined 
tracepoint. Canceling the user defined tracepoint does not affect the predefined 
tracepoint, and conversely. 


To cancel only user defined tracepoints, do not specify (PREDEFINED with the 
CANCEL TRACE command (/USER is the default). To cancel only predefined 
tracepoints, specify /PREDEFINED but not /USER. To cancel both user defined 
and predefined tracepoints, specify both /USER and /PREDEFINED. 


In general, the effect of the CANCEL TRACE command is symmetrical with 
that of the SET TRACE command (even though the SET TRACE command is 
used only with user defined tracepoints). Thus, to cancel a tracepoint that was 
established at a specific location, specify that same location (address expression) 
with the CANCEL TRACE command. To cancel tracepoints that were established 
on a class of instructions or events, specify the class of instructions or events 
with the corresponding qualifier (for example, /LINE, /BRANCH, /ACTIVATING, 
/EVENT=, and so on). See the qualifier descriptions for more specific information. 


Related commands: 


CANCEL ALL 
(SET,SSHOW,CANCEL) BREAK 
(SET,SSHOW) EVENT_FACILITY 
(SET,SSHOW) TRACE 
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CANCEL TRACE 


Examples 
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DBG> CANCEL TRACE MAIN\LOOP+10 

This command cancels the user defined tracepoint at the location 
MAIN\ LOOP+10. 

DBG> CANCEL TRACE/ALL 


This command cancels all user defined tracepoints. 


DBG_1> CANCEL TRACE/TERMINATING 


This command cancels a previous user defined SET TRACE/TERMINATING 
command. As a result, a tracepoint is not triggered when a process does an 
image exit. 


DBG> CANCEL TRACE/EVENT=RUN TASK 3 


This command cancels the tracepoint that was set to trigger when task 3 
(task ID = 3) entered the RUN state. 
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CANCEL TYPE/OVERRIDE 


Format 


Description 


Example 


Cancels the override type established by a previous SET TYPE/OVERRIDE 
command. 


CANCEL TYPE/OVERRIDE 


The CANCEL TYPE/OVERRIDE command sets the current override type to 
"none". As a result, a program location associated with a compiler generated 
type is interpreted according to that type. 


Related commands: 


DEPOSIT 
EXAMINE 
(SET,SHOW) EVENT_FACILITY 


DBG> CANCEL TYPE/OVERRIDE 
This command cancels the effect of a previous SET TYPE/OVERRIDE command. 
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CANCEL WATCH 


Format 


Parameters 


Qualifiers 


Description 


Examples 
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Cancels a watchpoint. 


CANCEL WATCH [address-expression{, . . . ]] 


address-expression 

Specifies a watchpoint to be canceled. With high-level languages, this is typically 
the name of a variable. Do not use the asterisk (*) wildcard character. Instead, 
use the /ALL qualifier. Do not specify an address expression with /ALL. 


/ALL 
Cancels all watchpoints. Do not specify an address expression with /ALL. 


The effect of the CANCEL WATCH command is symmetrical with the effect of 
the SET WATCH command. To cancel a watchpoint that was established at a 
specific location with the SET WATCH command, specify that same location 
with CANCEL WATCH. Thus, to cancel a watchpoint that was set on an entire 
aggregate, specify the aggregate in the CANCEL WATCH command; to cancel a 
watchpoint that was set on one element of an aggregate, specify that element in 
the CANCEL WATCH command. 


The CANCEL ALL command also cancels all watchpoints. 
Related commands: 


CANCEL ALL 
(SET,SHOW,CANCEL) BREAK 
(SET,SHOW,CANCEL) TRACE 
(SET,SSHOW) WATCH 


1. DBG> CANCEL WATCH SUB2\TOTAL 
This command cancels the watchpoint at variable TOTAL in module SUB2. 


2. DBG> CANCEL WATCH/ALL 


This command cancels all watchpoints you have set. 
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CANCEL WINDOW 


Format 


Parameters 


Qualifiers 


Description 


Example 


Permanently deletes a screen window definition. 


CANCEL WINDOW [window-namef{, . . . ]] 


window-name 

Specifies the name of a screen window definition to be canceled. Do not use the 
asterisk (*) wildcard character. Instead, use the /ALL qualifier. Do not specify a 
window name name with /ALL. 


/ALL 
Cancels all predefined and user-defined window definitions. Do not specify a 
window definition name with /ALL. 


When a window definition is canceled, you can no longer use its name in a 
DISPLAY command. The command does not affect any displays. 


Related commands: 


(SET,SHOW,CANCEL) DISPLAY 
(SET,SHOW) WATCH 


DBG> CANCEL WINDOW MIDDLE 


This command permanently deletes the screen window definition MIDDLE. 
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CONNECT 


CONNECT 


Format 


Parameters 


Description 
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Interrupts an image that is running without debugger control in another process 
and brings that process under debugger control. When used without a parameter, 
brings any spawned process that is waiting to connect to the debugger under 
debugger control. 


This command applies only to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 


CONNECT [process-spec[, .. . J] 


process-spec 

Specifies a process in which an image to be interrupted is running. The process 
must be in the same VMS job as the process in which the debugger was invoked. 
Use any of the following forms: 


[%PROCESS_NAME] process-name The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


[%PROCESS_NAME] "process-name" The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’ ) instead 
of quotation marks ("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


When you specify a process, the CONNECT command enables you to interrupt | 
an image that is running without debugger control in that process and bring the 
process under debugger control. The command is useful if, for example, you run 
a debuggable image with the DCL command RUN/NODEBUG or if your program 
issues a LIB$SPAWN run-time library call or a $CREPRC system service call 


that does not invoke the debugger. 


You can bring a process under debugger control in this manner only if that 
process is in the same VMS job as the process in which the debugger was invoked, 
and only if the image was not linked with the /NOTRACEBACK qualifier. Also, 
you have full symbolic information for that image only if its modules were 
compiled and linked with the /DEBUG command qualifier. 


When the process is brought under debugger control, execution of the image is 
suspended at the point at which it was interrupted. 


When you do not specify a process, the CONNECT command brings any processes 
that are waiting to connect to your debugging session under debugger control. If 
no process is waiting, you can press Ctrl/C to abort the CONNECT command. 


Debugger Command Dictionary 
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By default, a tracepoint is triggered when a process is brought under debugger 
control. This predefined tracepoint is equivalent to that resulting from entering 
the SET TRACE/ACTIVATING command. The process is then known to the 
debugger and can be identified in a SHOW PROCESS display. 


Related commands: 


Ctrl/Y 
(SET,SHOW,CANCEL) TRACE 


Examples 


1, DBG_1> CONNECT 


This command brings any processes that are waiting to be connected to the 
debugger under debugger control. 


2. DBG_1> CONNECT JONES 3 


This command interrupts the image running in process JONES_3 and brings 
the process under debugger control. Process JONES_3 must be in the same 
VMS job as the process in which the debugger was invoked. Also, the image 
must not have been linked with the /NOTRACEBACK qualifier. 
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Ctri/C 


Ctri/C 


Format 


Description 
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When entered from within a debugging session, aborts the execution of a 
debugger command or interrupts program execution without interrupting the 
debugging session. 


Note 


Do not use Ctrl/Y from within a debugging session. 


Pressing Ctrl/C enables you to abort the execution of a debugger command or to 
interrupt program execution without interrupting the debugging session. This is 
useful when, for example, the program is executing an infinite loop that does not 
have a breakpoint, or you want to abort a debugger command that takes a long 
time to complete. The debugger prompt is then displayed, so that you can enter 
debugger commands. 


After a Ctrl/C interruption, any processes of a multiprocess program that were 
executing images are in the "interrupted" state. 


If your program already has a Ctrl/C AST service routine enabled, use the SET 
ABORT_KEY command to assign the debugger’s abort function to another Ctrl- 
key sequence. Note, however, that many Ctrl-key sequences have VMS predefined 
functions, and the SET ABORT_KEY command enables you to override such 
definitions (see the VMS DCL Concepts Manual). Some of the Ctrl-key characters 
not used by the VMS operating system are G, K, N, and P. 


If your program does not have a Ctrl/C AST service routine enabled, and you 
assign the debugger’s abort function to another Ctrl-key sequence, the Ctrl/C 
sequence then behaves like Ctrl/Y—that is, it interrupts the debugging session 
and returns you to DCL level. 


Do not use Ctrl/Y from within a debugging session. Always use either Ctrl/C 
or an equivalent Ctrl-key sequence established with the SET ABORT_KEY 
command. 


You can use the SPAWN and ATTACH commands to leave and return to a 
debugging session without losing the debugging context. 


Related commands: 


ATTACH 

Ctrl/Y 

(SETSSHOW) ABORT_KEY 
SPAWN 
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Example 


DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 
1000: 0 

1004: 0 
1008: 0 
1012: 0 
1016: 0 
SDEBUG-W-ABORTED, command aborted by user request 
DBG> 


This example shows how to use the Ctrl/C sequence to, first, interrupt program 
execution, and then, abort the execution of a debugger command. 
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Ctrl/W, Cirl/Z 


Ctri/W, Ctri/Z 


Ctrl/W refreshes the screen in screen mode (like DISPLAY/REFRESH). 
Ctrl/Z ends a debugging session (like EXIT). 


Format 


Cirl/Z 


Description 


For an explanation of the Ctrl/W and Ctrl/Z commands, see the descriptions of 
the DISPLAY/REFRESH and EXIT commands, respectively. 
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Ctri/Y 


When entered from DCL level, interrupts an image that is running without 
debugger control, enabling you to then invoke the debugger with the DCL 
DEBUG command. 


Note 


Do not use Ctrl/Y from within a debugging session. Instead, use Ctrl/C or 
an equivalent abort-key sequence established with the SET ABORT_KEY 
command. 


Format 


Description 


Pressing Ctrl/Y at the DCL level enables you to interrupt an image that is 
running without debugger control, so that you can then invoke the debugger with 
the DCL command DEBUG. 


You can bring an image under debugger control only if, as a minimum, that image 
was linked with the /TRACEBACK qualifier (TRACEBACK is a LINK command 

default). Also, you can reference all of the image’s symbols while debugging only 

if its modules were compiled and linked with the /DEBUG qualifier (in that case, 

you could use the DCL command RUN/NODEBUG to execute the image without 

the debugger). 


When you press Ctrl/Y to interrupt the image’s execution, control is passed to 
the DCL command interpreter. If you then type the DCL command DEBUG, the 
interrupted image is brought under control of the debugger. The debugger sets its 
language dependent parameters to the source language of the module in which 
execution was interrupted and displays its prompt. You can then determine 
where execution was suspended by entering a SHOW CALLS command (and a 
SHOW PROCESS command, in the case of a multiprocess program). 


When a new debugging session is started, a process is created to run the main 
debugger image (DEBUGSHR.EXE) that controls the session. The main debugger 
process is a subprocess of the process that is running the image to be debugged. 
The debugger displays its banner when a new session is started. 


Other details about the effect of a Ctrl/Y-DEBUG sequence depend on the 
debugging configuration (default or multiprocess), which is determined by the 
current definition of the logical name DBG$PROCESS in the process where the 
interrupted image was executing. 


Default Debugging Configuration 

The default debugging configuration is achieved when DBG$PROCESS is either 
undefined or has the value DEFAULT. In this case a new default debugging 
session is started every time you invoke the debugger with the Ctrl/Y-DEBUG 
sequence (see Example 1). 
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Ctrl/Y 


Examples 
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Multiprocess Debugging Configuration 


The multiprocess debugging configuration is achieved when DBG$PROCESS has 
the job definition MULTIPROCESS. In this case, the effect of a Ctrl/Y—DEBUG 
sequence is as follows: 


If a multiprocess debugging session does not already exist in the same job 
as the process running the interrupted image, a new multiprocess debugging 
session is created (see Example 2). 


If a multiprocess debugging session already exists in the same job, the 
interrupted image and its process come under control of that session. In this 
case the debugger does not display its banner. 


Within a debugging session, you can use the CONNECT command to connect an 
image that is running without debugger control in another process (of the same 
job) to that debugging session. 


Related commands: 


CONNECT 
Ctrl/C 
$ DEBUG (at DCL level) 


$ RUN/NODEBUG TEST B 


Interrupt 
$ DEBUG 


VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is ADA, module set to SWAP 
DBG> 


The RUN/NODEBUG command executes the image TEST_B without 
debugger control. Execution is interrupted with Ctrl/Y. The DEBUG command 
then causes the debugger to be invoked. The debugger displays its banner, 
sets the language-dependent parameters to the language (Ada, in this case) 
of the module (SWAP) in which execution was interrupted, and displays the 
prompt. This is the default debugging configuration, as indicated by the 
DBG> prompt. 


$ DEFINE/JOB DBGSPROCESS MULTIPROCESS 
$ RUN/NODEBUG PROG2 


Interrupt 


$ DEBUG 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is FORTRAN, module set to SUB4 
predefined trace on activation at SUB4\%LINE 12 in PROCESS NUMBER 1 
DBG_1> 
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The DEFINE/JOB command establishes a multiprocess debugging 
configuration. The RUN/NODEBUG command executes the image PROG2 
without debugger control. The Ctrl/Y—DEBUG sequence interrupts execution 
and invokes the debugger. The VAX DEBUG banner indicates that a new 
debugging session has been started. The process-specific prompt (DBG_1>) 
indicates that this is a multiprocess configuration and that execution is 
suspended in process 1, which is running PROG2. The activation tracepoint 
indicates where execution was interrupted when the debugger took control of 
the process. 
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DECLARE 


DECLARE 


Format 


Parameters 


Description 
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Declares a formal parameter within a command procedure. This enables you 
to pass an actual parameter to the procedure when entering an @ (Execute 
Procedure) command. 


DECLARE p-name:p-kind [,p-name:p-kind[, .. . J] 


p-name 
Specifies a formal parameter (a symbol) that is declared within the command 
procedure. 


Do not specify a null parameter (represented either by two consecutive commas 
or by a comma at the end of the command). 


p-kind 
Specifies the parameter kind of a formal parameter. Valid keywords are as 
follows: 


ADDRESS Specifies that the actual parameter is interpreted as an address 
expression. Has the same effect as the command DEFINE 
/ADDRESS p-name = actual-parameter. 


COMMAND _ Specifies that the actual parameter is interpreted as a command. 
Has the same effect as the command DEFINE/COMMAND 
p-name = actual-parameter. 


VALUE Specifies that the actual parameter is interpreted as a value 
expression in the current language. Has the same effect as the 
command DEFINE/VALUE p-name = actual-parameter. 


The DECLARE command is valid only within a command procedure. 


The DECLARE command binds one or more actual parameters, specified on 
the command line following the @ (Execute Procedure) command, to formal 
parameters (symbols) declared within a command procedure. 


Each p-name:p-kind pair specified by a DECLARE command binds one formal 
parameter to one actual parameter. Formal parameters are bound to actual 
parameters in the order in which the debugger processes the parameter 
declarations. If you specify several formal parameters on a single DECLARE 
command, the leftmost formal parameter is bound to the first actual parameter, 
the next formal parameter is bound to the second, and so on. If you use a 
DECLARE command in a loop, the formal parameter is bound to the first actual 
parameter on the first iteration of the loop; the same formal parameter is bound 
to the second actual parameter on the next iteration, and so on. 


Each parameter declaration acts like a DEFINE command: it associates a formal 
parameter with an address expression, a command, or a value expression in 

the current language, according to the parameter kind specified. The formal 
parameters themselves are consistent with those accepted by the DEFINE 
command and can in fact be deleted from the symbol table with the DELETE 


Examples 


Debugger Command Dictionary 
DECLARE 


command. For more information, see the descriptions of the DEFINE and 
DELETE commands. 


The %PARCNT built-in symbol, which can be used only within a command 
procedure, enables you to pass a variable number of parameters to a command 
procedure. The value of %7PARCNT is the number of actual parameters passed to 
the command procedure. 


Related commands: 


@ (Execute Procedure) 
DEFINE 
DELETE 


1, | ***** Command Procedure EXAM.COM ***** 
SET OUTPUT VERIFY 
DECLARE K:ADDRESS 
EXAMINE K 


DBG> @EXAM ARR4 
@DEBUG-I-VERIFYIC, entering command procedure EXAM 
DECLARE K:ADDRESS 


EXAMINE K 
PROG_8\ARR4 
(13 18 
(2): 1 
(3): 0 
(4): 1 
SDEBUG-I-VERIFYIC, exiting command procedure EXAM 
DBG> 


In this example, the DECLARE K:ADDRESS command declares the formal 
parameter K within command procedure EXAM.COM. When EXAM.COM 
is executed, the actual parameter passed to EXAM.COM is interpreted as 
an address expression, and the EXAMINE K command displays the value of 
that address expression. The SET OUTPUT VERIFY command causes the 
commands to echo when they are read by the debugger. 


At the debugger prompt, the @EXAM ARR4 command executes EXAM.COM, 
passing the actual parameter ARR4. Within EXAM.COM, ARR4 is 
interpreted as an address expression (an array variable, in this case). 


2. ! ***** Debugger Command Procedure EXAM GO.COM ***** 
DECLARE L:ADDRESS, M: COMMAND 
EXAMINE L; M 


DBG> @EXAM GO X "@DUMP" 
In this example, the command procedure EXAM_GO.COM accepts two 


parameters, an address expression (L) and a command string (M). The 
address expression is then examined and the command is executed. 


At the debugger prompt, the @EXAM_GO X "@DUMP" command executes 
EXAM_GO.COM, passing the address expression X and the command string 
@DUMP. 
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3. 


! ***k** Debugger Command Procedure VAR.DBG ***** 

SET OUTPUT VERIFY 

FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 

DBG> @VAR.DBG 12,37,45 

SDEBUG-I-VERIFYIC, entering command procedure VAR.DBG 
FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 
12 

37 

45 

¢DEBUG-I-VERIFYIC, exiting command procedure VAR.DBG 

DBG> 


In this example, the command procedure VAR.DBG accepts a variable number 
of parameters. That number is stored in the built-in symbol %PARCNT. 


At the debugger prompt, the @VAR.DBG command executes VAR.DBG, 
passing the actual parameters 12, 37, and 45. Therefore, ZPARCNT has the 
value 3, and the FOR loop is repeated 3 times. The FOR loop causes the 
DECLARE command to bind each of the three actual parameters (starting 
with 12) to a new declaration of X. Each actual parameter is interpreted as 
a value expression in the current language, and the EVALUATE X command 
displays that value. 


DEFINE 


Format 


Parameters 


Qualifiers 


Description 


Debugger Command Dictionary 
DEFINE 


Assigns a symbolic name to an address expression, command, or value. 


DEFINE symbol-name=parameter [,symbol-name=parameter[, . . . J] 


symbol-name 

Specifies a symbolic name to be assigned to an address, command, or value. The 
symbolic name can be composed of alphanumeric characters and underscores. 
The debugger converts lowercase alphabetic characters to uppercase. The first 
character must not be a number. The symbolic name must be no more than 31 
characters long. 


parameter 
Depends on the qualifier specified. 


/ADDRESS 
Specifies that the defined symbol is an abbreviation for an address expression. In 
this case, parameter is an address expression. DEFINE/ADDRESS is the default. 


/COMMAND 

Specifies that the defined symbol is treated as a new debugger command. In 
this case, parameter is a quoted character string. This qualifier provides, in 
simple cases, essentially the same capability as the DCL command "symbol := 
string." To define complex commands, you might need to use command procedures 
with formal parameters. For more information about declaring parameters to 
command procedures, see the description of the DECLARE command. 


/LOCAL 

Specifies that the definition remain local to the command procedure in which the 
DEFINE command is issued. The defined symbol is not visible at the debugger 
command level. By default, a symbol defined within a command procedure is 
visible outside that procedure. 


NVALUE 
Specifies that the defined symbol is an abbreviation for a value. In this case, 
parameter is a language expression in the current language. 


The DEFINE/ADDRESS command enables you to assign a symbolic name to 

an address expression in your program. For example, you can define a symbol 
for a nonsymbolic program location or for a symbolic program location having a 
long pathname prefix. Then, you can refer to that program location by the newly 
defined symbol. The /ADDRESS qualifier is the default definition qualifier. 


The DEFINE/COMMAND command enables you to define abbreviations for 
debugger commands or even define new commands, either from the debugger 
command level or from command procedures. 
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DEFINE 


Examples 
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The DEFINE/VALUE command enables you to assign a symbolic name to a value 
(or the result of evaluating a language expression). 


Use the /LOCAL qualifier to confine symbol definitions to command procedures. 
By default, defined symbols are global (visible outside the command procedure). 


If you plan to enter several DEFINE commands with the same qualifier, you 
can first use the SET DEFINE command to establish a new default qualifier 
(for example, SET DEFINE COMMAND makes the DEFINE command behave 
like DEFINE/COMMAND). Then you do not have to use that qualifier with 
the DEFINE command. You can override the current default qualifier for the 
duration of a single DEFINE command by specifying another qualifier. 


In symbol translation, the debugger searches symbols you define during the 
debugging session first. So if you define a symbol that already exists in your 
program, the debugger translates the symbol according to its defined definition, 
unless you specify a pathname prefix. 


If a symbol is redefined, the previous definition is canceled, even if different 
qualifiers were used with the DEFINE command. 


Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands 
are available only when the image in whose context they were created is the 
current image. If you use the SET IMAGE command to establish a new current 
image, these definitions are temporarily unavailable. Definitions created with the 
DEFINE/COMMAND and DEFINE/KEY commands are always available for all 
images, however. 


Use the SHOW SYMBOL/DEFINED command to determine the equivalence 
value of a symbol. 


Use the DELETE command to cancel a symbol definition. 
Related commands: 


DECLARE 

DELETE 

SET IMAGE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 


1. DBG> DEFINE CHK=MAIN\LOOP+10 
This command assigns the symbol CHK to the address MAIN\ LOOP+10. 


2. DBG> DEFINE/VALUE COUNTER=0 
DBG> SET TRACE/SILENT R DO (DEFINE/VALUE COUNTER = COUNTER+1) 


In this example, the first command assigns a value of 0 to the symbol 
COUNTER. The second command causes the debugger to increment the value 
of the symbol COUNTER by 1 whenever address R is encountered. In other 
words, this example counts the number of calls to R. 


3. DBG> DEFINE/COMMAND BRE = "SET BREAK" 


This command assigns the symbol BRE to the debugger command SET 
BREAK. 
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DEFINE/KEY 


Assigns a string to a function key. 


Format 
DEFINE/KEY key-name "equiv-string" 
Parameters 
key-name 
Specifies a function key to be assigned a string. Valid key names are as follows: 
Key Name LK201 Keyboard VT100-Type VT52-Type 
PF1 PF1 PF1 Blue 
PF2 PF2 PF2 Red 
PF3 PF3 PF3 Black 
PF4 PF4 PF4 
KPO0-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9 
PERIOD Keypad period (:) Keypad period (.) 
COMMA Keypad comma (, ) Keypad comma (, ) 
MINUS Keypad minus (—) Keypad minus (—) 
ENTER ENTER ENTER ENTER 
El Find 
E2 Insert Here 
E3 Remove 
B4 Select 
E5 Prev Screen 
E6 Next Screen 
HELP Help 
DO Do 
F6-F20 F6—F20 


On LK201 keyboards: 
¢ You cannot define keys F1 to F5 or the arrow keys (E7 to E10). 


¢ You can define keys F6 to F14 only if you have first entered the DCL 
command SET TERMINAL/NOLINE_EDITING. In that case, the line-editing 
functions of the LEFT and RIGHT arrow keys (E8 and EQ) are disabled. 


equiv-string 

Specifies the string to be processed when the specified key is pressed. Typically, 
this is one or more debugger commands. If the string includes any space or 
nonalphanumeric characters (for example, a semicolon separating two commands) 
enclose the string in quotation marks ("), 
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DEFINE/KEY 

Qualifiers 
/ECHO (default) 
/NOECHO 


Description 
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Controls whether the command line is displayed after the key has been pressed. 
Do not use /NOECHO with /NOTERMINATE. 


/IF_STATE=(state-name[, ... ]) 
/NOIF_STATE (default) | 
Specifies one or more states to which a key definition applies. The IF_STATE 
qualifier assigns the key definition to the specified states. You can specify 
predefined states, such as DEFAULT and GOLD, or user-defined states. A state 
name can be any appropriate alphanumeric string. The /NOIF_STATE qualifier 
assigns the key definition to the current state. 


/LOCK_STATE 

/NOLOCK_STATE (default) 

Controls how long the state set by /SET_STATE remains in effect after the 
specified key is pressed. The /LOCK_STATE qualifier causes the state to remain 
in effect until it is changed explicitly (for example, with a SET KEY/STATE 
command). The /NOLOCK_STATE qualifier causes the state to remain in effect 
only until the next terminator character is typed, or until the next defined 
function key is pressed. 


/LOG (default) 

/NOLOG 

Controls whether a message is displayed indicating that the key definition has 
been successfully created. The /LOG qualifier displays the message. 


/SET_STATE=state-name 

/NOSET_STATE (default) 

Controls whether pressing the key changes the current key state. The /SET_ 
STATE qualifier causes the current state to change to the specified state when 
you press the key. The /NOSET_STATE qualifier causes the current state to 
remain in effect. 


/TERMINATE 

/NOTERMINATE (default) 

Controls whether the specified string is terminated (processed) when the key is 
pressed. The /TERMINATE qualifier causes the string to be terminated when the 
key is pressed. The /NOTERMINATE qualifier enables you to press other keys 
before terminating the string by pressing the Return key. 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 


The DEFINE/KEY command enables you to assign a string to a function key, 
overriding any predefined function that was bound to that key (the predefined 
key functions are listed in Appendix B). When you then press the key, the 
debugger enters the currently associated string into your command line. The 
DEFINE/KEY command is like the DCL DEFINE/KEY command. 


Examples 
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On VT52- and VT100-series terminals, the function keys you can use include all 
of the numeric keypad keys. Newer terminals and workstations have the LK201 
keyboard. On LK201 keyboards, the function keys you can use include all of the 
numeric keypad keys, the nonarrow keys of the editing keypad (Find, Insert Here, 
and so on), and keys F6 to F20 at the top of the keyboard. 


A key definition remains in effect until you redefine the key, enter the DELETE 
/KEY command for that key, or exit the debugger. You can include key definitions 
in a command procedure, such as your debugger initialization file. 


The /AF_STATE qualifier enables you to increase the number of key definitions 
available on your terminal. The same key can be assigned any number of 
definitions as long as each definition is associated with a different state. 


By default, the current key state is the "DEFAULT" state. The current state can 
be changed with the SET KEY/STATE command, or by pressing a key that causes 
a state change (a key that was defined with the DEFINE/KEY/LOCK_STATE 
/STATE qualifier combination). 


Related commands: 


DELETE/KEY 
(SET,SSHOW) KEY 


1. DBG> SET KEY/STATE=GOLD 
$DEBUG-I-SETKEY, keypad state has been set to GOLD 
DBG> DEFINE/KEY/TERMINATE KP9 "SET RADIX/OVERRIDE HEX" 
SDEBUG-I-DEFKEY, GOLD key KP9 has been defined 
DBG> 


In this example, the SET KEY command establishes GOLD as the current 
key state. The DEFINE/KEY command assigns the SET RADIX/OVERRIDE 
HEX command to keypad key 9 for the current state (GOLD). The command 
is processed when the key is pressed. 


2. DBG> DEFINE/KEY/IF STATE=BLUE KP9 "SET BREAK %LINE " 
SDEBUG-I-DEFKEY, BLUE key KP9 has been defined 
DBG> 


This command assigns the unterminated command string "SET BREAK 
%LINE" to keypad key 9 for the BLUE state. After pressing the keypad key 
sequence BLUE-KP9, you can enter a line number and then press the Return 
key to terminate and process the SET BREAK command. 


3. DBG> SET KEY/STATE=DEFAULT 
SDEBUG-I-SETKEY, keypad state has been set to DEFAULT 
DBG> DEFINE/KEY/SET STATE=RED/LOCK_STATE F12 "" 
SDEBUG-I-DEFKEY, DEFAULT key F12 has been defined 
DBG> 


In this example, the SET KEY command establishes DEFAULT as the current 
state. The DEFINE/KEY command makes key F12 (LK201 keyboard) a state 
key. Pressing F12 while in the DEFAULT state causes the current state to 
become RED. The key definition is not terminated and has no other effect 

(a null string is assigned to F12). After pressing F12, you can enter "RED" 
commands by pressing keys that have definitions associated with the RED 
state. 
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DEFINE/PROCESS GROUP 


Format 


Parameters 
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Assigns a symbolic name to a list of process specifications. 


Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


DEFINE/PROCESS_GROUP _ process-group-name =process-spec[, .. . ] 


process-group-name 

Specifies a symbolic name to be assigned to a list of process specifications. The 
symbolic name can be composed of alphanumeric characters and underscores. 
The debugger converts lowercase alphabetic characters to uppercase. The first 
character must not be a number. The symbolic name must be no more than 31 
characters long. 


process-spec 
Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


[%PROCESS_NAME] "process-name" The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’ ) instead 
of quotation marks ("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER proc-number The number assigned to a process 

(or %PROC proc-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 
%PREVIOUS_PROCESS The process previous to the visible 


process in the debugger’s circular 
process list. 


%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


If you do not specify a process, the symbolic name is created but contains no 
process entries. 


Description 


Examples 
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The DEFINE/PROCESS_GROUP command assigns a symbol to list of process 
specifications. You can then use the symbol in any command where a list of 
process specifications is allowed. 


The DEFINE/PROCESS_GROUP command does not verify the existence of a 
specified process. This enables you to specify processes that do not yet exist. 


To identify a symbol that was defined with the DEFINE/PROCESS_GROUP 
command, use the SHOW SYMBOL/DEFINED command. To delete a symbol that 
was defined with the DEFINE/PROCESS_GROUP command, use the DELETE 


command. 


Related commands: 


DELETE 
(SET,SSHOW) DEFINE 
SHOW SYMBOL/DEFINED 


DBG_1> DEFINE/PROCESS GROUP SERVERS=FILE SERVER, NET SERVER 
DBG_1> SHOW PROCESS SERVERS 


Number Name Hold State Current PC 

* 1 FILE SERVER step FS PROG\SLINE 37 
2 NETWORK_SERVER break NET PROG\%LINE 24 

DBG 1> 


This DEFINE/PROCESS_GROUP command assigns the symbolic name 
SERVERS to the process group consisting of FILE_LSERVER and NETWORK_ 
SERVER. The SHOW PROCESS SERVERS command displays information 
about the processes that make up the group SERVERS. 


USER_3> DEFINE/PROCESS GROUP Gl=sPROCESS NUMBER 1, %VISIBLE PROCESS 
USER_3> SHOW SYMBOL/DEFINED Gi 
defined Gl 
bound to: "SPROCESS NUMBER 1, %VISIBLE PROCESS" 
was defined /process_ group 
USER_3> DELETE Gl 


This DEFINE/PROCESS_GROUP command assigns the symbolic name G1 to 
the process group consisting of process 1 and the visible process (process 3). 
The SHOW SYMBOL/DEFINED G1 command identifies the defined symbol 
G1. The DELETE G1 command deletes the symbol from the DEFINE symbol 
table. 


DBG_2> DEFINE/PROCESS_ GROUP A = B,C,D 
DBG 2> DEFINE/PROCESS GROUP B = E,F,G 
DBG 2> DEFINE/PROCESS GROUP E = I,J,A 
SDEBUG-E-NORECSYM, recursive PROCESS GROUP symbol definition 


encountered at or near "A" 
DBG 2> 


This series of DEFINE/PROCESS_GROUP commands illustrate valid and 
invalid uses of the command. 
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DELETE 


Format 


Parameters 


Qualifiers 


Description 


Examples 
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Deletes a symbol definition that was established with the DEFINE command. 
DELETE [symbol-namef[, ... ]] 


symbol-name 

Specifies a symbol whose definition is to be deleted from the DEFINE symbol 
table. Do not use the asterisk (*) wildcard character. Instead, use the /ALL 
qualifier. Do not specify a symbol name with /ALL. If you use the /LOCAL 
qualifier, the symbol specified must have been previously defined with the 
DEFINE/LOCAL command. If you do not specify /LOCAL, the symbol specified 
must have been previously defined with the DEFINE command without /LOCAL. 


/ALL 

Deletes all global DEFINE definitions. If you also specify /LOCAL, deletes all 
local DEFINE definitions associated with the current command procedure (but 
not the global DEFINE definitions). Do not specify a symbol name with /ALL. 


/LOCAL 

Deletes the (local) definition of the specified symbol from the current command 
procedure. The symbol must have been previously defined with the DEFINE 
/LOCAL command. 


The DELETE command deletes either a global DEFINE symbol or a local 
DEFINE symbol. A global DEFINE symbol is a symbol defined with the DEFINE 
command without the /LOCAL qualifier. A local DEFINE symbol is a symbol 
defined in a debugger command procedure with the DEFINE/LOCAL command, 
so that its definition is confined to that command procedure. 


Related commands: 


DECLARE 

DEFINE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 


1. DBG> DEFINE X = INARR, Y = OUTARR 
DBG> DELETE X,Y 
In this example, the DEFINE command defines X and Y as global symbols 
corresponding to INARR and OUTARR, respectively. The DELETE command 
deletes these two symbol definitions from the global symbol table. 
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2. DBG> DELETE/ALL/LOCAL 


In this example, the DELETE/ALL/LOCAL commmand deletes all local 
symbol definitions from the current command procedure. 
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DELETE/KEY 


Deletes a key definition that was established with the DEFINE/KEY command or, 
by default, by the debugger. 


Format 
DELETE/KEY [key-name] 
Parameters 
key-name 
Specifies a key whose definition is to be deleted. Do not use the asterisk (*) 
wildcard character. Instead, use the /ALL qualifier. Do not specify a key name 
with /ALL. Valid key names are as follows: 
Key Name LK201 Keyboard VT100-Type VT52-Type 
PF1 PF1 PF1 Blue 
PF2 PF2 PF2 Red 
PF3 PF3 PF3 Black 
PF4 PF4 PF4 
KPO-KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9 
PERIOD Keypad period (. ) Keypad period (.) 
COMMA Keypad comma (, ) Keypad comma (, ) 
MINUS Keypad minus (—) Keypad minus (—) 
ENTER ENTER ENTER ENTER 
E1 ' Find 
E2 Insert Here 
E38 Remove 
B4 Select 
B5 Prev Screen 
E6 Next Screen 
HELP Help 
DO Do 
F6-F20 F6—F20 
Qualifiers 


/ALL . 
Deletes all key definitions in the specified state. Do not specify a key name with 
/ALL. If you do not specify a state, all key definitions in the current state are 
deleted. Use the /STATE qualifier to specify one or more states. 


/LOG (default) 

/NOLOG 

Controls whether a message is displayed indicating that the specified key 
definitions have been deleted. The /LOG qualifier displays the message. 
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Description 


Examples 
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/STATE=(state-name [, ... ]) 

/NOSTATE (default) 

Selects one or more states for which a key definition is to be deleted. The /STATE 
qualifier deletes key definitions for the specified states. You can specify predefined 
key states, such as DEFAULT and GOLD, or user-defined states. A state name 
can be any appropriate alphanumeric string. The /NOSTATE qualifier deletes the 
key definition for the current state only. 


By default, the current key state is the "DEFAULT" state. The current state can 


_be changed with the SET KEY/STATE command, or by pressing a key that causes 


a state change (a key that was defined with the DEFINE/KEY/LOCK_STATE 
/STATE qualifier combination). 


The DELETE/KEY command is like the DCL command DELETE/KEY. 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 


Related commands: 


DEFINE/KEY 
(SET,SSHOW) KEY 


1. DBG> DELETE/KEY KP4 
SDEBUG-I-DELKEY, DEFAULT key KP4 has been deleted 
DBG> 


This command deletes the key definition for keypad key KP4 in the state last 
set by the SET KEY command (by default, this is the DEFAULT state). 


2. DBG> DELETE/KEY/STATE=(BLUE,RED) COMMA 
SDEBUG-I-DELKEY, BLUE key COMMA has been deleted 
SDEBUG-I-DELKEY, RED key COMMA has been deleted 
DBG> 


This command deletes the key definition for keypad key COMMA in the 
BLUE and RED states. 


CD-57 


Debugger Command Dictionary 


DEPOSIT 


DEPOSIT 


Format 


Parameters 


Qualifiers 
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Changes the value of a program variable. More generally, deposits a new value at 
the location denoted by an address expression. 


DEPOSIT address-expression = language-expression 


address-expression 

Specifies the location into which the value of the language expression is to be 
deposited. With high-level languages, this is typically the name of a variable 

and can include a pathname to specify the variable uniquely. More generally, 

an address expression can also be a memory address or a register and can be 
composed of numbers (offsets) and symbols, as well as one or more operators, 

operands, or delimiters. Appendix D identifies the debugger’s built-in symbols 
for the VAX registers and identifies the operators that can be used in address 
expressions. 


You cannot specify an entire aggregate variable (a composite data structure such 
as an array or a record). To specify an individual array element or a record 
component, use the syntax of the current language. 


See Chapter 11 for information that is specific to vector registers and vector 
instructions. 


language-expression 

Specifies the value to be deposited. You can specify any language expression that 
is valid in the current language. For most languages, the expression can include 
the names of simple (noncomposite, single-valued) variables but not the names 
of aggregate variables (such as arrays or records). If the expression contains 
symbols with different compiler generated types, the debugger uses the rules of 
the current language to evaluate the expression. | 


If the expression is an ASCII string or a VAX assembly-language instruction, you 
must enclose it in quotation marks (") or apostrophes (’). If the string contains 
quotation marks or apostrophes, use the other delimiter to enclose the string. 


If the string has more characters (1-byte ASCII) than can fit into the program 
location denoted by the address expression, the debugger truncates the extra 
characters from the right. If the string has fewer characters, the debugger pads 
the remaining characters to the right of the string by inserting ASCII space 
characters. 


/ASCIC 

Deposits a counted ASCII string into the specified location. You must specify a 
string on the right-hand side of the equal sign. The deposited string is preceded 
by a 1-byte count field that gives the length of the string. /AC is also accepted. 
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/ASCID 

Deposits an ASCII string into the address given by a string descriptor that is 
at the specified location. You must specify a string on the right-hand side of the 
equal sign. The specified location must contain a string descriptor. If the string 
lengths do not match, the string is either truncated on the right or padded with 
space characters on the right. /AD is also accepted. 


/ASCII:n 

Deposits n bytes of an ASCII string into the specified location. You must specify 
a string on the right-hand side of the equal sign. If its length is not n, the string 
is truncated or padded with space characters on the right. If n is omitted, the 
actual length of the data item at the specified location is used. 


/ASCIW 

Deposits a counted ASCII string into the specified location. You must specify a 
string on the right-hand side of the equal sign. The deposited string is preceded 
by a 2-byte count field that gives the length of the string. /AW is also accepted. 


/ASCIZ 

Deposits a zero-terminated ASCII string into the specified location. You must 
specify a string on the right-hand side of the equal sign. The deposited string 
is terminated by a zero byte that indicates the end of the string. /AZ is also 
accepted. 


/BYTE 
Deposits a 1-byte integer into the specified location. 


/D_FLOAT 

Converts the expression on the right-hand side of the equal sign to the D_floating 
type (length 8 bytes) and deposits the result into the specified location. Values 
of type D_floating can range from .29 * 10~%8 to 1.7 « 1088 with approximately 16 
decimal digits precision. 


/DATE_TIME 

Converts a string representing a date and time (for example, 21-DEC-1988 
_21:08:47.15) to the VMS internal format for date and time and deposits that 
value (length 8 bytes) into the specified location. Specify an absolute date and 
time in the following format: [dd-mmm-yyyy[:]] [hh:mm:ss.cc]. 


/FLOAT 

Converts the expression on the right-hand side of the equal sign to the F_floating 
type (length 4 bytes) and deposits the result into the specified location. Values 
of type F_floating can range from .29 « 10-8 to 1.7 « 10°8 with approximately 7 
decimal digits precision. 


/G_FLOAT 

Converts the expression on the right-hand side of the equal sign to the G_floating 
type (length 8 bytes) and deposits the result into the specified location. Values of 
type G_floating can range from .56 « 10-298 to .9 » 10°98 with approximately 15 
decimal digits precision. 


/H_FLOAT 

Converts the expression on the right-hand side of the equal sign to the H_floating 
type (length 16 bytes) and deposits the result into the specified location. Values 
of type H_floating can range from .84 « 1074982 to .59 « 10498? with approximately 
33 decimal digits precision. 
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Description 


/INSTRUCTION 

Deposits a VAX assembly-language instruction into the specified location. The 
expression on the right-hand side of the equal sign must be a string representing 
a VAX instruction. 


/LONGWORD 
Deposits a longword integer (length 4 bytes) into the specified location. 


/OCTAWORD 
Deposits an octaword integer (length 16 bytes) into the specified location. 


/PACKED:n 
Converts the expression on the right-hand side of the equal sign to a packed 
decimal representation and deposits the resulting value into the specified 


location. The value of n is the number of decimal digits. Each digit occupies one 
nibble (4 bits). 


/QUADWORD 
Deposits a quadword integer (length 8 bytes) into the specified location. 


TASK 
Applies to tasking (multithread) programs. 


Deposits a task value (a task name or a task ID such as TASK 3) into the 
specified location. The deposited value must be a valid task value. 


/TYPE=(name) 

Converts the expression to be deposited to the type denoted by name (which must 
be the name of a variable or data type declared in the program), then deposits 
the resulting value into the specified location. This enables you to specify a 
user-declared type. 


You must use parentheses around the type expression. 


/WORD 
Deposits a word integer (length 2 bytes) into the specified location. 


The DEPOSIT command can be used to change the contents of any memory 
location or register that is accessible in your program. For high-level languages 
the command is used mostly to change the value of a variable (an integer, real, 


_ string, array, record, and so on). 
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The DEPOSIT command is like an assignment statement in most programming 
languages. The value of the expression specified to the right of the equal sign is 
assigned to the variable or other location specified to the left of the equal sign. 
For Ada and Pascal, you can use ":=" instead of "=" in the command syntax. 


The debugger recognizes the compiler-generated types associated with symbolic 
address expressions (symbolic names declared in your program). Symbolic 
address expressions include the following entities: 


¢ Variable names. When specifying a variable with the DEPOSIT command, 
use the same syntax that is used in the source code. 
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DEPOSIT 


¢ Routine names, labels, and line numbers. These are associated with VAX 
instructions. You can deposit instructions using basically the same techniques 
as when depositing into string variables. However, you must also use the 
AINSTRUCTION qualifier or first enter a SET TYPE INSTRUCTION or SET 
TYPE/OVERRIDE INSTRUCTION command. 


In general, when you enter a DEPOSIT command, the debugger takes the 
following action: 


e It evaluates the address expression specified to the left of the equal sign, to 
yield a program location. 


¢ Ifthe program location has a symbolic name, the debugger associates the 
location with the symbol’s compiler generated type. If the location does not 
have a symbolic name (and, therefore, no associated compiler generated 
type) the debugger associates the location with the type longword integer by 
default. This means that, by default, you can deposit integer values that do 
not exceed 4 bytes into these locations. 


See Chapter 11 for information that is specific to vector registers and vector 
instructions. 


e It evaluates the language expression specified to the right of the equal sign, 
in the syntax of the current language and in the current radix, to yield a 
value. The current language is the language last established with the SET 
LANGUAGE command. If no SET LANGUAGE command was entered, the 
current language is, by default, the language of the module containing the 
main program. 


e It checks that the value and type of the language expression is consistent 
with the type of the address expression. If you try to deposit a value that 
is incompatible with the type of the address expression, the debugger issues 
a diagnostic message. If the value is compatible, the debugger deposits the 
value into the location denoted by the address expression. 


The debugger might do type conversion during a deposit operation if the language 
rules allow it. For example a real value that is specified to the right of the equal 
sign might be converted to an integer value if it is being deposited into a location 
with an integer type. In general, the debugger tries to follow the assignment 
rules for the current language. 


There are several ways of changing the type associated with a program location 
so that you can deposit data of a different type into that location: 


¢ To change the default type for all locations that do not have a symbolic name, 
you can specify a new type with the SET TYPE command. 


¢ To change the default type for all locations (both those that do and do not 
have a symbolic name), you can specify a new type with the SET TYPE 
/OVERRIDE command. 


¢ To override the type currently associated with a particular location for the 
duration of a single DEPOSIT command, you can specify a new type by means 
of a qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). 


The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. The default radix for both data entry 
and display is decimal for all languages except BLISS and MACRO. It is 
hexadecimal for BLISS and MACRO. You can use the SET RADIX and SET 
RADIX/OVERRIDE commands to change the default radix. 
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The DEPOSIT command sets the current entity built-in symbols %CURLOC 
and period (.) to the location denoted by the address expression specified. Logical 
predecessors (%PREVLOC and circumflex (“)) and successors (%NEXTLOC and 
pressing the Return key) are based on the value of the current entity. 


Related commands: 


CANCEL TYPE/OVERRIDE 
EVALUATE 

EXAMINE 
(SET,SHOW,CANCEL) RADIX 
(SET,SSHOW) TYPE 


1. DBG> DEPOSIT I = 7 


This command deposits the value 7 into the integer variable I. 


2. DBG> DEPOSIT WIDTH = CURRENT WIDTH + 24.80 


This command deposits the value of the expression CURRENT_WIDTH + 
24.80 into the real variable WIDTH. . 


38. DBG> DEPOSIT STATUS = FALSE 
This command deposits the value FALSE into the Boolean variable STATUS. 


4, DBG> DEPOSIT PART NUMBER = "WG-7619,3-84" 


This command deposits the string WG-7619.3-84 into the string variable 
PART_NUMBER. 


5. DBG> DEPOSIT EMPLOYEE.ZIPCODE = 02172 


This command deposits the value 02172 into component ZIPCODE of record 
EMPLOYEE. 


6. DBG> DEPOSIT. ARR(8) = 35 
DBG> DEPOSIT * = 14 


The first DEPOSIT command deposits the value 35 into element 8 of array 
ARR. As a result, element 8 becomes the current entity. The second command 
deposits the value 14 into the logical predecessor of element 8, namely 
element 7. 


7. DBG> FOR I = 1 TO 4 DO (DEPOSIT ARR(I) = 0) 
This command deposits the value 0 into elements 1 to 4 of array ARR. 


8. DBG> DEPOSIT COLOR = 3 
SDEBUG-E-OPTNOTALLOW, operator "DEPOSIT" not allowed on given 
data type 
DBG> 


The debugger alerts you when you try to deposit data of the wrong type 
into a variable (in this case, if you try to deposit an integer value into an 
enumerated type variable). The E (error) message severity indicates that the 
debugger does not make the assignment. 


10. 


Ii. 


12. 


13. 


14. 


15. 
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DBG> DEPOSIT VOLUME = - 100 
SDEBUG-I-IVALOUTBNDS, value assigned is out of bounds at or near '-’ 
DBG> 


The debugger alerts you when you try to deposit an out-of-bounds value into 
a variable (in this case a negative value). The I (informational) message 
severity indicates that the debugger does make the assignment. 


DBG> DEPOSIT/BYTE WORK = %HEX 21 


This command deposits the expression %HEX 21 into location WORK and 
converts it to a byte integer. 


DBG> DEPOSIT/OCTAWORD BIGINT = 111222333444555 


This command deposits the expression 111222333444555 into location 
BIGINT and converts it to an octaword integer. 


DBG> DEPOSIT/FLOAT BIGFLT = 1.11949*10**35 


This command converts 1.11949*10**85 to an F_floating type value and 
deposits it into location BIGFLT. 


DBG> DEPOSIT/ASCII:10 WORK+20 = 'abcdefghij}’ 


This command deposits the string "abcdefghij" into the location that is 20 
bytes beyond that denoted by the symbol WORK. 


DBG> DEPOSIT/INSTR SUB2+2 = ‘MOVL #20A,RO0’ 


This command deposits the instruction MOVL #20A,R0’ into the location 
SUB2 + 2 bytes. | 


DBG> DEPOSIT/TASK VAR = %TASK 2 
DBG> EXAMINE/HEX VAR 
SAMPLE.VAR: 0016A040 

DBG> EXAMINE/TASK VAR 
SAMPLE.VAR: %TASK 2 

DBG> 


The DEPOSIT command deposits the Ada task value %TASK 2 into location 
VAR. The subsequent EXAMINE commands display the contents of VAR in 
hexadecimal format and as a task value, respectively. 


CD-63 


Debugger Command Dictionary 
DISABLE AST 


DISABLE AST 


Format 


Description 


Example 
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Disables the delivery of asynchronous system traps (ASTs) in your program. 


DISABLE AST 


The DISABLE AST command disables the delivery of ASTs in your program and 
thereby prevents interrupts from occurring while the program is running. If ASTs 
are delivered while the debugger is running (processing commands, and so on), 
they are queued and are delivered when control is returned to the program. 


The ENABLE AST command reenables the delivery of ASTs, including any 
pending ASTs (ASTs waiting to be delivered). 


Related commands: (ENABLE,SHOW) AST. 


DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 


The DISABLE AST disables the delivery of ASTs in your program, as confirmed 
with the SHOW AST command. 


DISPLAY 


Format 


Parameters 
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Creates a new screen display or modifies an existing display. 


DISPLAY [display-name [AT window-spec] [display-kind] [, ... ]] 


display-name 
Specifies the display to be created or modified. 


If you are creating a new display, specify a name that is not already used as a 
display name. 


If you are modifying an existing display, you can specify any of the following 
entities: 


¢ A predefined display: SRC, OUT, PROMPT, INST, REG 
¢ A display previously created with the DISPLAY command 
e A display built-in symbol: 


%CURDISP 
%CURSCROLL 
%NEXTDISP 
%NEXTINST 
%NEXTOUTPUT 
%NEXTSCROLL 
%NEXTSOURCE 


You must specify this parameter unless you use /GENERATE (parameter 
optional), or (REFRESH (parameter not allowed). 


You can specify more than one display, each with an optional window specification 
and display kind. 


window-spec 

Specifies the screen window at which the display is to be positioned. You can 
specify any of the following entities: 

e A predefined window. For example, RH1 (right top half). See Appendix C. 

e A window definition previously established with the SET WINDOW command. 


¢ A window specification of the form (start-line, line-count [,start- 
column, column-count]). The specification can include expressions which 
can be based on the built-in symbols %PAGE and %WIDTH (for example, 
%WIDTH/4). 


If you omit the w-spec parameter, the screen position depends on whether you are 
specifying an existing display or a new display: 


¢ Ifyou are specifying an existing display, the position of the display is not 
changed. 


e If you are specifying a new display, it is positioned at window H1 or H2, 
alternating between H1 and H2 each time you create another display. 
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disp-kind 


Specifies the display kind. Valid keywords are as follows: 


DO (command{[; .. . }) 


INSTRUCTION 


INSTRUCTION (command) 


OUTPUT 


REGISTER 


SOURCE 


SOURCE (command) 


Specifies an automatically updated output 
display. The commands are executed in the 
order listed each time the debugger gains 
control. Their output forms the contents of the 
display. If you specify more than one command, 
they must be separated by semicolons. 


Specifies an instruction display. If selected 

as the current instruction display with 

the SELECT/INSTRUCTION command, it 
displays the output from subsequent EXAMINE 
ANSTRUCTION commands. 


Specifies an automatically updated instruction 
display. The command specified must be an 
EXAMINE/AINSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 


Specifies an output display. If selected as 

the current output display with the SELECT 
/OUTPUT command, it displays any debugger 
output that is not directed to another display. 
If selected as the current input display with the 
SELECT/INPUT command, it echoes debugger 
input. If selected as the current error display 
with the SELECT/ERROR command, it displays 
debugger diagnostic messages. 


Specifies an automatically updated register 
display. The display is updated each time the 
debugger gains control. 


Specifies a source display. If selected as the 
current source display with the SELECT 
/SOURCE command, it displays the output 
from subsequent TYPE or EXAMINE/SOURCE 


commands. 


Specifies an automatically updated source 
display. The command specified must be a 
TYPE or EXAMINE/SOURCE command. 
The source display is updated each time the 
debugger gains control. 


You cannot change the display kind of the PROMPT display. 


If you omit the disp-kind parameter, the display kind depends on whether you 
are specifying an existing display or a new display: 


¢ Ifyou are specifying an existing display, the display kind is not changed. 


¢ Ifyou are specifying a new display, an OUTPUT display is created. 


Qualifiers 
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/CLEAR 
Erases the entire contents of a specified display. Do not use /CLEAR when 
creating a new display. Do not use /(GENERATE with /CLEAR. 


/DYNAMIC (default) 

/NODYNAMIC 

Controls whether a display automatically adjusts its window dimensions 
proportionally when the screen height or width is changed by a SET TERMINAL 
command. By default (DYNAMIC), all user-defined and predefined displays, 
adjust their dimensions automatically. 


/GENERATE 

Regenerates the contents of a specified display. Only automatically generated 
displays are regenerated. These include DO displays, register displays, 
source (cmd-list) displays, and instruction (cmd-list) displays. The debugger 
automatically regenerates all these kinds of displays before each prompt. If 
no display is specified, regenerates the contents of all automatically generated 
displays. Do not use /GENERATE when creating a new display. Do not use 
/CLEAR with /GENERATE. 


/HIDE 

Places a specified display at the bottom of the display pasteboard. This hides 
the specified display behind any other displays that share the same region of the 
screen. You cannot hide the PROMPT display. 


The /HIDE qualifier has the same effect as /PUSH. 


/MARK_CHANGE 

/NOMARK_CHANGE (default) 

Controls whether the lines that change in a DO display each time it is 
automatically updated are marked. When you use /MARK_CHANGE, any lines 
in which some contents have changed since the last time the display was updated 
are highlighted in reverse video. This qualifier is particularly useful when you 
want any variables in an automatically updated display to be highlighted when 
they change. 


The /NOMARK_CHANGE qualifier (default) specifies that any lines that change 
in DO displays are not to be marked. This qualifier cancels the effect of a 
previously entered /MARK_CHANGE qualifier on the specified display. 


This qualifier is not applicable to other kinds of displays. 


/POP (default) 

/NOPOP 

Controls whether a specified display is placed at the top of the display pasteboard, 
ahead of any other displays but behind the PROMPT display. By default (/POP), 
the display is placed at the top of the pasteboard and hides any other displays 
that share the same region of the screen, except for the PROMPT display. This is 
the default action of the DISPLAY command. 


The /NOPOP qualifier preserves the order of all displays on the pasteboard (same 
effect as /NOPUSH). 
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/PROCESS[=(process-spec)] 

/NOPROCESS (default) 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


Controls whether the specified display is process specific—that is, whether the 
specified display is associated only with a particular process. The contents of a 
process-specific display are generated and modified in the context of that process. 
You can make any display process specific, except for the PROMPT display. 


The /PROCESS=(process-spec) qualifier causes the specified display to be 
associated with the specified process. You must include the parentheses. Use 
any of the following process-spec forms: 


[%PROCESS_NAME] process-name The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


[%PROCESS_NAME] "process-name" The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’) instead 
of quotation marks (" ). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER proc-number The number assigned to a process 
(or %PROC proc-number) when it comes under debugger control. 


Process numbers appear in a SHOW 
PROCESS display.. 
process-group-name A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 
%PREVIOUS_PROCESS The process previous to the visible 


process in the debugger’s circular 
process list. 

%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


The /PROCESS qualifier causes the specified display to be associated with the 
process that was the visible process when the DISPLAY/PROCESS command was 
executed. 


The /NOPROCESS qualifier causes the specified display to always be associated 
with the visible process, which might change during program execution. This is 
the default behavior. 


If you do not specify /PROCESS, the current process-specific behavior (if any) of 
the specified display remains unchanged. 


See also /SUFFIX. 
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/PUSH 

/NOPUSH 

The /PUSH qualifier has the same effect as /HIDE. The /NOPUSH qualifier 
preserves the order of all displays on the pasteboard (same effect as /NOPOP). 


/REFRESH 
Refreshes the terminal screen. Do not specify any command parameters with 
/REFRESH. You can also use Ctrl/W to refresh the screen. 


/REMOVE 

Marks the display as being removed from the display pasteboard, so it is not 
shown on the screen unless you explicitly request it with another DISPLAY 
command. Although a removed display is not visible on the screen, it still exists 
and its contents are preserved. You cannot remove the PROMPT display. 


/SIZE:n 

Sets the maximum size of a display to n lines. If more than n lines are written to 
the display, the oldest lines are lost as the new lines are added. If you omit this 
qualifier, the maximum size of the display is as follows: 


¢ Ifyou specify an existing display, the maximum size is unchanged. 
e¢ Ifyou are creating a display, the default size is 64 lines. 


For an output or DO display, /SIZE:n specifies that the display should hold the 
n most recent lines of output. For a source or instruction display, n gives the 
number of source lines or lines of instructions that can be placed in the memory 
buffer at any one time. However, you can scroll a source display over the entire 
source code of the module whose code is displayed (source lines are paged into 
the buffer as needed). Similarly, you can scroll an instruction display over all of 
the instructions of the routine whose instructions are displayed (instructions are 
decoded from the image as needed). 


/SUFF1X[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


See also /[NOJPROCESS. 
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The DISPLAY command can be used to create a display or modify an existing 
display. 


To create a display, specify a name that is not already used as a display name 
(the SHOW DISPLAY command identifies all existing displays). 


By default, the DISPLAY command places a specified display on top of the display 
pasteboard, ahead of any other displays but behind the PROMPT display, which 
cannot be hidden. The specified display thus hides the portions of other displays 
(except for the PROMPT display) that share the same region of the screen. 


See Appendix B for keypad-key definitions associated with the DISPLAY 
command. 


Related commands: 


Ctrl/W 

EXPAND 

MOVE 

SET PROMPT 

(SET,SSHOW) TERMINAL 
(SET,SSHOW,CANCEL) WINDOW 
SELECT 

(SHOW,CANCEL) DISPLAY 


1. DBG> DISPLAY REG 


This command shows the predefined register display, REG, at its current 
window location. 


2. DBG> DISPLAY/PUSH INST 


This command pushes display INST to the bottom of the display pasteboard, 
behind all other displays. 


38. DBG> DISPLAY NEWDISP AT RT2 
DBG> SELECT/INPUT NEWDISP 


In this example, the DISPLAY command shows the user-defined display 
NEWDISP at the right middle third of the screen. The SELECT/INPUT 
command selects NEWDISP as the current input display. NEWDISP now 
echoes debugger input. 


4. DBG> DISPLAY DISP2 AT RS45 
DBG> SELECT/OUTPUT DISP2 


In this example, the DISPLAY command creates a display named DISP2 
essentially at the right bottom half of the screen, above the PROMPT display, 
which is located at S6. This is an output display by default. The SELECT 
/OUTPUT command then selects DISP2 as the current output display. 
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DBG> SET WINDOW TOP AT (1,8,45,30) 
DBG> DISPLAY NEWINST AT TOP INSTRUCTION 
DBG> SELECT/INST NEWINST 


In this example, the SET WINDOW command creates a window named TOP 
starting at line 1 and column 45, and extending down for 8 lines and to the 
right for 30 columns. The DISPLAY command creates an instruction display 


named NEWINST to be displayed through TOP. The SELECT/INST command 
selects NEWINST as the current instruction display. 


DBG> DISPLAY CALLS AT Q3 DO (SHOW CALLS) 


This command creates a DO display named CALLS at window Q3. Each time 
the debugger gains control from the program, the SHOW CALLS command 
is executed and the output is displayed in display CALLS, replacing any 
previous contents. 


DBG> DISPLAY/MARK EXAM AT Q2 DO (EXAMINE A,B,C) 


This command creates a DO display named EXAM at window Q2. The display 
shows the current values of variables A, B, and C whenever the debugger 
prompts for input. Any changed values are highlighted. 


DBG_3> DISPLAY/PROCESS OUT_X AT S4 


This command makes display OUT_X specific to the visible process (process | 
3) and puts the display at window S4. 


DBG_2> DISPLAY/PROCESS OUT_/SUFFIX AT S45 OUTPUT 


This command creates an output display at window $45. The /PROCESS 
qualifier, by default, makes the display specific to the visible process (process 
2, in this example). The /SUFFIX qualifier appends a process-identifying 
suffix, that denotes the visible process, to the display name OUT_. By 
default, the /SUFFIX qualifier appends the same process identifier suffix that 
appears on the prompt. Therefore, the full display name is OUT_2. 
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Executes a debugger command in the context of one or more processes. 


Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


DO (command; ... ]) 


command 
Specifies a debugger command that is to be executed in the context of the 
processes specified. 


/PROCESS=(process-spec[, . . . ]) 

Specifies one or more processes in whose context the commands are executed. 
You must include the parentheses even if only one process is specified. If you do 
not specify /PROCESS, the commands are executed in the context of all processes 
(this effect is also achieved if you specify the asterisk (*) wildcard character for 
process-spec). 


Use any of the following forms: 


[%PROCESS_NAME] process-name The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


- [%PROCESS_NAME] "process-name" The VMS process name, if that name 
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contains space or lowercase characters. 
You can also use apostrophes (’) instead 
of quotation marks (" ). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER proc-number The number assigned to a process 
(or %PROC proc-number) when it comes under debugger control. 


Process numbers appear in a SHOW 
PROCESS display. 
process-group-name A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 
%PREVIOUS_PROCESS The process previous to the visible 


process in the debugger’s circular 
process list. 


Description 


Examples 
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%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


By default, commands are executed in the context of the visible process. The 
DO command enables you to execute commands in the context of one or more 
processes that are currently under debugger control (this is also referred to 

as "broadcasting" commands to processes). The DO command is equivalent to 
entering a SET PROCESS/VISIBLE command for each process specified with the 
/PROCESS qualifier (or for all processes, if /PROCESS is not specified) and then 
entering the specified commands. 


To change the visible process, use the SET PROCESS command. 


When using the DO command, note that a hold condition in the visible process 
(as established with the SET PROCESS/HOLD command) is ignored. 


Related command: SET PROCESS. 


1. DBG_2> DO (SHOW CALLS) 
For sPROCESS NUMBER 1 


module name routine name line rel PC abs PC 

*MOD4 SUB3 31; QOO00001E 0000041E 
For SPROCESS NUMBER 2 

module name routine name line rel PC abs PC 

*MOD3 SUB1 4 0000000B 0000040B 
DBG_2> 


This command executes a SHOW CALLS command in the context of all 
processes that are currently under debugger control. 


2. DBG 3> DO/PROCESS=(%PROC 2,%PROC 1) (EVAL/ADDR X;EXAM X) 
For SPROCESS NUMBER 2 
SDEBUG-E-NOSYMBOL, symbol ‘’X’ is not in the symbol table 
For %Process number 1 
512 
TEST\X: 1 
DBG 3> 


This command executes the two commands EVAL/ADDR X and EXAM Xi in 
the context of processes 2 and 1. 
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Invokes the editor established with the SET EDITOR command. If no SET 
EDITOR command was entered, invokes the VAX Language-Sensitive Editor, if 
that editor is installed on your system. 


EDIT  [[module-name\] line-number] 


module-name 

Specifies the name of the module whose source file is to be edited. If you specify a 
module name, you must also specify a line number. If you omit the module name . 
parameter, the source file whose code appears in the current source display is 
chosen for editing. 


line-number 

A positive integer that specifies the source line on which the editor’s cursor is 
initially placed. If you omit this parameter, the cursor is initially positioned 

at the beginning of the source line that is centered in the debugger’s current 
source display, or at the beginning of line 1 if the editor was set to /NOSTART_ 
POSITION (see the SET EDITOR command description). 


/EXIT 

/NOEXIT (default) 

Controls whether you end the debugging session prior to invoking the editor. If 
you specify /EXIT, the debugging session is terminated and the editor is then 
invoked. If you specify /NOEXIT, the editing session is started and you return to 
your debugging session after terminating the editing session. 


If you have not specified an editor with the SET EDITOR command, the EDIT 
command invokes the VAX Language-Sensitive Editor in a spawned subprocess 
(if the VAX Language-Sensitive Editor is installed on your system). The typical 
(default) way to use the EDIT command is not to specify any parameters. In this 
case, the editing cursor is initially positioned at the beginning of the line that 

is centered in the currently selected debugger source display (the current source 
display). 


The SET EDITOR command provides options for invoking different editors, either 
in a subprocess or through a callable interface. 


Related commands: 


(SET,SHOW) EDITOR 
(SET,SHOW,CANCEL) SOURCE 


Examples 
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DBG> EDIT 


In this example, the EDIT command spawns the VAX Language-Sensitive 
Editor in a subprocess to edit the source file whose code appears in the 
current source display. The editing cursor is positioned at the beginning of 
the line that was centered in the source display. 


DBG> EDIT SWAP\12 


In this example, the EDIT command spawns the VAX Language-Sensitive 
Editor in a subprocess to edit the source file containing the module SWAP. 
The editing cursor is positioned at the beginning of source line 12. 


DBG> SET EDITOR/CALLABLE EDT 
DBG> EDIT 


In this example, the SET EDITOR/CALLABLE_EDT command establishes 
that EDT is the default editor and is invoked through its callable interface 
(rather than spawned in a subprocess). The EDIT command invokes EDT 
to edit the source file whose code appears in the current source display. The 


editing cursor is positioned at the beginning of source line 1, because the 
default qualifier /NOSTART_POSITION applies to EDT. 
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Enables the delivery of asynchronous system traps (ASTs) in your program. 


ENABLE AST 


The ENABLE AST command enables the delivery of ASTs while your program is 
running, including any pending ASTs (ASTs waiting to be delivered). If ASTs are 
delivered while the debugger is running (processing commands, and so on), they 

are queued and are delivered when control is returned to the program. Delivery 

of ASTs in your program is initially enabled by default. 


Related commands: (DISABLE,SHOW) AST. 


DBG> ENABLE AST 
DBG> SHOW AST 
ASTs are enabled 
DBG> 


The ENABLE AST command enables the delivery of ASTs in your program, as 
confirmed with the SHOW AST command. 


EVALUATE 


Format 


Parameters 


Qualifiers 


Description 
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Evaluates a language expression in the current language (by default, the 
language of the module containing the main program). 


EVALUATE language-expressior[, ... ] 


language-expression 
Specifies any valid expression in the current language. 


/BINARY 
Specifies that the result be displayed in binary radix. 


/CONDITION_VALUE 

Specifies that the expression be interpreted as a VMS condition value (the kind 
of condition value you would specify using the condition-handling mechanism). 
The message text corresponding to that condition value is then displayed. The 
specified value must be an integer value. 


/DECIMAL 
Specifies that the result be displayed in decimal radix. 


/HEXADECIMAL | 
Specifies that the result be displayed in hexadecimal radix. 


/OCTAL 
Specifies that the result be displayed in octal radix. 


The debugger interprets the expression specified in an EVALUATE command as a 
language expression, evaluates it in the syntax of the current language and in the 
current radix, and displays its value as a literal (for example, an integer value) in 
the current language. 


The current language is the language last established with the SET LANGUAGE 
command. If no SET LANGUAGE command was entered, the current language 
is, by default, the language of the module containing the main program. 


If an expression contains symbols with different compiler generated types, the 
debugger uses the type-conversion rules of the current language to evaluate the 
expression. 


The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. The current radix is the radix last 
established with the SET RADIX command. If no SET RADIX command was 
entered, the current radix for both data entry and display is, by default, decimal 
for all languages except BLISS and MACRO. It is hexadecimal for BLISS and 
MACRO. You can use a radix qualifier with the EVALUATE command (/BINARY, 
/OCTAL, and so on) to display integer data in another radix. These qualifiers do 
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not affect how the debugger interprets the data you specify—that is, they override 
the current output radix, but not the input radix. 


The EVALUATE command sets the current value built-in symbols %CURVAL 
and backslash (\ ) to the value denoted by the specified expression. 


Debugger support for language-specific operators and constructs is described in 
Appendix E. 


Related commands: 


EVALUATE/ADDRESS 
(SET,SHOW) LANGUAGE 
(SET,SHOW,CANCEL) RADIX 
(SET,SSHOW) TYPE 


1. DBG> EVALUATE 100.34 * (14.2 + 7.9) 
2217.514 
DBG> 


This command uses the debugger as a calculator by multiplying 100.34 by 
(14.2 + 7.9). 


2. DBG> EVALUATE/OCTAL X 
00000001512 
DBG> 


This command evaluates the symbol X and displays the result in octal radix. 


3. DBG> EVALUATE TOTAL + CURR_AMOUNT 
8247.20 
DBG> 


This command evaluates the sum of the values of two real variables, TOTAL 
and CURR_AMOUNT. 


4. DBG> DEPOSIT WILLING = TRUE 
DBG> DEPOSIT ABLE = FALSE 
DBG> EVALUATE WILLING AND ABLE 
False 
DBG> 


In this example, the EVALUATE command evaluates the logical AND of the 
current values of two Boolean variables, WILLING and ABLE. 


5. DBG> EVALUATE COLOR’ FIRST 
RED 
DBG> 


In this Ada example, this command evaluates the first element of the 
enumeration type COLOR. 
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Parameters 


Qualifiers 


Description 


Evaluates an address expression and displays the result as a memory address or 
a register name. 


EVALUATE/ADDRESS _address-expression[, .. . ] 


address-expression 
Specifies an address expression of any valid form (for example, a routine name, a 
variable name, a label, a line number, and so on). 


/BINARY 
Specifies that the memory address is displayed in binary radix. 


/DECIMAL 
Specifies that the memory address is displayed in decimal radix. 


/HEXADECIMAL 
Specifies that the memory address is displayed in hexadecimal radix. 


/OCTAL 
Specifies that the memory address is displayed in octal radix. 


The EVALUATE/ADDRESS command enables you to determine the memory 
address or register associated with an address expression. 


The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. The default radix for both data entry and 
display is decimal for all languages except BLISS and MACRO. It is hexadecimal 
for BLISS and MACRO. You can use a radix qualifier with the EVALUATE 
command (/BINARY, /OCTAL, and so on) to display address values in another 
radix. These qualifiers do not affect how the debugger interprets the data you 
specify—that is, they override the current output radix, but not the input radix. 


If the value of a variable is currently stored in a register instead of memory, the 
EVALUATE/ADDRESS command identifies the register. The radix qualifiers have 
no effect in that case. 


The EVALUATE/ADDRESS command sets the current entity built-in symbols 
%CURLOC and period (.) to the location denoted by the address expression 
specified. Logical predecessors (%PREVLOC and circumflex (“ )) and successors 
(%NEXTLOC and pressing the Return key) are based on the value of the current 
entity. 
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Related commands: 


EVALUATE 

(SET. SHOW,CANCEL) RADIX 
SHOW SYMBOL/ADDRESS 
SYMBOLIZE 


DBG> EVALUATE/ADDRESS MODNAME\%LINE 110 
3942 
DBG> 


This command displays the memory address denoted by the address 
expression MODNAME\ %LINE 110. 


DBG> EVALUATE/ADDRESS/HEX A,B,C 
000004A4 

000004AC 

000004A0 

DBG> 


This command displays the memory addresses denoted by the address 
expressions A, B, and C in hexadecimal radix. 


DBG> EVALUATE/ADDRESS X 
MOD3\%R1 
DBG> 


This command indicates that variable X is associated with register Rl. Xis a 
nonstatic (register) variable. 


EXAMINE 


Format 


Parameters 


Qualifiers 
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Displays the current value of a program variable. More generally, displays the 
value of the entity denoted by an address expression. 


EXAMINE  [address-expression[:address-expression] [, .. . ]] 


address-expression 

Specifies an entity to be examined. With high-level languages, this is typically the 
name of a variable and can include a pathname to specify the variable uniquely. 
More generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the debugger’s built-in 
symbols for the VAX registers and identifies the operators that can be used in 
address expressions. 


If you specify the name of an aggregate variable (a composite data structure 
such as an array or record structure) the debugger displays the values of all 
elements. For an array, the display shows the subscript (index) and value of each 
array element. For a record, the display shows the name and value of each record 
component. 


To specify an individual array element, array slice, or record component, use the 
syntax of the current language. 


If you specify a range of entities, the value of the address expression that denotes 
the first entity in the range must be less than the value of the address expression 
that denotes the last entity in the range. The debugger displays the entity 
specified by the first address expression, the logical successor of that address 
expression, the next logical successor, and so on, until it displays the entity 
specified by the last address expression. You can specify a list of ranges by 
separating ranges with a comma. 


See Chapter 11 and the descriptions of the /TMASK, /FMASK, and /OPERANDS 
qualifiers for information that is specific to vector registers and vector 
instructions. 


/ASCIC 

Interprets each examined entity as a counted ASCII string preceded by a 1-byte 
count field that gives the length of the string. The string is then displayed. The 
/AC qualifier is also accepted. 


/ASCID 

Interprets each examined entity as the address of a string descriptor pointing 

to an ASCII string. The CLASS and DTYPE fields of the descriptor are not 
checked, but the LENGTH and POINTER fields provide the character length and 
address of the ASCII string. The string is then mabe The /AD qualifier is 
also accepted. 
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/ASCII:n 

Interprets and displays each examined entity as an ASCII string of length n bytes 
(n characters). If n is omitted, the debugger attempts to determine a length from 
the type of the address expression. 


/ASCIW 

Interprets each examined entity as a counted ASCII string preceded by a 2-byte 
count field that gives the length of the string. The string is then displayed. The 
/AW qualifier is also accepted. 


/ASCIZ 

Interprets each examined entity as a zero-terminated ASCII string. The ending 
zero byte indicates the end of the string. The string is then displayed. The /AZ 
qualifier is also accepted. 


/BINARY 
Displays each examined entity as a binary integer. 


/BYTE 
Displays each examined entity in the byte integer type (length 1 byte). 


/CONDITION_VALUE 
Interprets each examined entity as a condition-value return status and displays 
the message associated with that return status. 


/D_FLOAT 

Displays each examined entity in the D_floating type (length 8 bytes). Values of 
type D_floating can range from .29 « 10~8 to 1.7 « 10°° with approximately 16 
decimal digits precision. 


/DATE_TIME 

Interprets each examined entity as a quadword integer (length 8 bytes) containing 
the internal VMS representation of date and time. Displays the value in the 
format dd-mmm-yyyy hh:mm:ss.xx. 


/DECIMAL . 
Displays each examined entity as a decimal integer. 


/DEFAULT 
Displays each examined entity in the default radix. 


/FLOAT 

Displays each examined entity in the F_floating type (length 4 bytes). Values 
of type F_floating can range from .29 « 10788 to 1.7 « 108° with approximately 7 
decimal digits precision. 


/FMASK[=(mask-address-expression)] 
Applies to vectorized programs. 


See /TMASK. 


/G_FLOAT 

Displays each examined entity in the G_floating type (length 8 bytes). Values of 
type G_floating can range from .56 * 10—2°8 to .9 « 10°98 with approximately 15 
decimal digits precision. 
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/H_FLOAT 

Displays each examined entity in the H_floating type (length 16 bytes). Values of 
type H_floating can range from .84 * 10-4982 to 59 « 104932 with approximately 33 
decimal digits precision. 


/HEXADECIMAL 
Displays each examined entity as a hexadecimal integer. 


[INSTRUCTION 

Displays each examined entity as a VAX assembly-language instruction (variable 
length, depending on the number of instruction operands and the kind of 
addressing modes used). See also /OPERANDS. 


In screen mode, the output of an EXAMINE/JINSTRUCTION command is directed 
at the current instruction display, if any, not at an output or DO display. The 
arrow in the instruction display points to the examined instruction. 


/LINE (default) 

/NOLINE 

Controls whether program locations are displayed in terms of line numbers 
(%LINE x) or as routine-name + byte-offset. By default (/LINE), the debugger 
symbolizes program locations in terms of line numbers. 


/LONGWORD 

Displays each examined entity in the longword integer type (length 4 bytes). This 
is the default type for program locations that do not have a compiler generated 
type. 


/OCTAL 
Displays each examined entity as an octal integer. 


/OCTAWORD 
Displays each examined entity in the octaword integer type (length 16 bytes). 


/OPERANDS[=keyword] 

Displays operand information associated with an examined instruction (displays 
each operand’s address and its contents, using the operand’s data type). The 
keywords BRIEF and FULL vary the amount of information displayed about any 
nonregister operands. The default is /OPERANDS=BRIEF. 


Use /OPERANDS only when examining the instruction at the current PC value 
(for example, EXAMINE/OPERANDS .0\%PC). Examining the operands of 

an instruction that is not at the current PC value can give erroneous results, 
because the state of the machine (the contents of the registers) is not set up for 
that instruction. 


In screen mode, operand information is directed at the current output display. 


When you examine the operands of a vector instruction, any operand-element 
masking that might be associated with that instruction is performed by default. 
The /T[MASK and /FMASK qualifiers enable you to specify some other mask. The 
current value of the vector length register (VLR) limits the highest element of a 
vector register that you can examine. 


See also the SET MODE [NOJOPERANDS=keyword command. It enables you 
to set a default level for the amount of operand information displayed when 
examining instructions. 
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/PACKED:n 
Interprets each examined entity as a packed decimal number. The value of n is 
the number of decimal digits. Each digit occupies one nibble (4 bits). 


/PSL 
Displays each examined entity in PSL (processor status longword) format. 


/PSW 
Displays each examined entity in PSW (processor status word) format. The /PSW 
qualifier is like /PSL except that only the low order word (2 bytes) is displayed. 


/QUADWORD 
Displays each examined entity in the quadword integer type (length 8 bytes). 


/SOURCE 

Displays the source line corresponding to the location of each examined entity. 
The examined entity must be associated with a machine code instruction and, 
therefore, must be a line number, a label, a routine name, or the memory address 
of an instruction. The examined entity cannot be a variable name or any other 
address expression that is associated with data. 


In screen mode, the output of an EXAMINE/SOURCE command is directed at the 
current source display, if any, not at an output or DO display. The arrow in the 
source display points to the source line associated with the last entity specified 
(or the last one specified in a list of entities). 


/SYMBOLIC (default) 

/NOSYMBOLIC 

Controls whether symbolization occurs. By default (SYMBOLIC), the debugger 
symbolizes all addresses, if possible; that is, it converts numeric addresses into 
their symbolic representation. If you specify /NOSYMBOLIC, the debugger 
suppresses symbolization of entities you specify as absolute addresses. If you 
specify entities as variable names, symbolization still occurs. The /(NOSYMBOLIC 
qualifier is useful if you are interested in identifying numeric addresses rather 
than their symbolic names (if symbolic names exist for those addresses). If you 
specify /NOSYMBOLIC, command processing might speed up somewhat, because 
the debugger does not need to convert numbers to names. 


/TASK 
Applies to tasking (multithread) programs. 


Interprets each examined entity as a task (thread) object and displays the task 
value (the name or task ID) of that task object. 


When examining a task object, use the /TASK qualifier only if the programming 
language does not have built-in tasking services. 


/TMASK[=(mask-address-expression)] 
/FMASK[=(mask-address-expression)] 
These qualifiers apply to vectorized programs. 


These qualifiers enable you to specify a mask in order to display certain elements 
of a vector register (VO to V15), or of an array in memory, while not displaying 
other elements. 


For example, when you examine the operands of a vector instruction (by using 
the /OPERANDS qualifier), these qualifiers enable you to override any operand- 
element masking that might be associated with that instruction. 


Description 
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The /TMASK qualifier applies the EXAMINE command only to the elements of 
the register or array that correspond to the set bits (bit value: 1) of the mask. 
The /FMASK qualifier applies the EXAMINE command only to the elements that 
correspond to the clear bits (bit value: 0) of the mask. The current value of the 
vector length register (VLR) limits the highest register element that you can 
examine but not the highest array element. 


By default, if you do not specify a mask address expression with /TMASK or 
/FMASK, the vector mask register (VMR) is used. That is, the EXAMINE 
command is applied only to the elements of the vector register or array that 
correspond to the set bits (in the case of /TMASK) or clear bits (in the case of 
/FMASK) of VMR. 


If you specify a mask address expression with /T[MASK or /FMASK, the value at 
that address is used as the mask, subject to the following conventions: 


¢ You must use parentheses around the address expression. 


¢ The number of mask elements limits the number of register or array elements 
that you can examine. 


¢ Ifthe mask address expression denotes a Boolean array, its values are used 
as the mask, in the same basic way that VMR is used in the default case. 


e Ifthe mask address expression denotes a non-Boolean array, the least 
significant bit value of each array element is used as the mask for the 
corresponding element of the register or target array. 


e Ifthe mask address expression denotes a Boolean scalar type, its value is 
used as the mask for the first element of the register or target array. No 
other elements are examined. 


e Ifthe mask address expression denotes any other type, its least significant bit 
value is used as the mask for the first element of the register or target array. 
No other elements are examined. 


¢ For a multi-element mask, the lowest specified element of the mask is applied 
to the lowest specified element of the register or target array. 


/TYPE=(name) 


Interprets and displays each examined entity according to the type specified 


by name (which must be the name of a variable or data type declared in the 
program). This enables you to specify a user-declared type. 


/WORD 
Displays each examined entity in the word integer type (length 2 bytes). 


The EXAMINE command displays the entity at the location denoted by an 
address expression. The command can be used to display the contents of any 
memory location or register that is accessible in your program. For high-level 
languages the command is used mostly to obtain the current value of a variable 
(an integer, real, string, array, record, and so on). 


The debugger recognizes the compiler-generated types associated with symbolic 
address expressions (symbolic names declared in your program). Symbolic 
address expressions include the following entities: 


¢ Variable names. When specifying a variable with the EXAMINE command, 
use the same syntax that is used in the source code. 
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¢ Routine names, labels, and line numbers. These are associated with VAX 
instructions. You can examine instructions using the same techniques as 
when examining variables. 


In general, when you enter an EXAMINE command, the debugger evaluates 
the address expression specified to yield a program location. The debugger then 
displays the value stored at that location as follows: 


¢ Ifthe location has a symbolic name, the debugger formats the value according 
to the compiler generated type associated with that symbol—that is, as a 
variable of a particular type or as a VAX instruction. 


e Ifthe location does not have a symbolic name (and, therefore, no associated 
compiler generated type) the debugger formats the value in the type longword 
integer by default. This means that, by default, the EXAMINE command 
displays the contents of these locations as longword (4-byte) integer values. 


See Chapter 11 and the descriptions of the /TMASK, /FMASK, and /OPERANDS 
qualifiers for information that is specific to vector registers and vector 
instructions. 


There are several ways of changing the type associated with a program location 
so that you can display the data at that location in another data format: 


¢ To change the default type for all locations that do not have a symbolic name, 
you can specify a new type with the SET TYPE command. 


¢ To change the default type for all locations (both those that do and do not 
have a symbolic name), you can specify a new type with the SET TYPE 
/OVERRIDE command. 


¢ To override the type currently associated with a particular location for the 
duration of a single EXAMINE command, you can specify a new type by 
means of a type qualifier (/ASCII:n, /BYTE, /TYPE=(name), and so on). Most 
of the EXAMINE command qualifiers are type qualifiers. 


The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. The default radix for both data entry and 
display is decimal for all languages except BLISS and MACRO. It is hexadecimal 
for BLISS and MACRO. The EXAMINE command has four radix qualifiers 
(/BINARY, /DECIMAL, /HEXADECIMAL, /OCTAL) that enable you to display 
data in another radix. You can also use the SET RADIX and SET RADIX 
/OVERRIDE commands to change the default radix. 


In addition to the type and radix qualifiers, the EXAMINE command has 
qualifiers for other purposes: 


¢ The /SOURCE qualifier enables you to identify the line of source code 
corresponding to a line number, routine name, label, or any other address 
expression that is associated with an instruction rather than data. 


¢ The /[NOJLINE and /[NOJSYMBOL qualifiers enable you to control the 
symbolization of address expressions. 


The EXAMINE command sets the current entity built-in symbols 2CURLOC 
and period (.) to the location denoted by the address expression specified. Logical 
predecessors (%PREVLOC and circumflex (“)) and successors (ZNEXTLOC and 
pressing the Return key) are based on the value of the current entity. 


Examples 
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Related Commands: 


CANCEL TYPE/OVERRIDE 
DEPOSIT 

EVALUATE 

SET MODE [NOJOPERANDS 
SET MODE [NO]SYMBOLIC 
(SET,SSHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 


DBG> EXAMINE COUNT 
SUB2\COUNT: 27 
DBG> 


This command displays the value of the integer variable COUNT, in module 
SUB2. . 


DBG> EXAMINE PART NUMBER 
INVENTORY\PART_ NUMBER: "LP-3592.6-84" 
DBG> 


This command displays the value of the string variable PART_NUMBER. 


DBG> EXAMINE SUB1\ARR3 


SUB1\ARR3 
(1,1): 27.01000 
(1y2)2 31.01000 
(1,3)2 12.48000 
(2,1): 15.08000 
(2,2): 22.30000 
(2,3) 18.73000 

DBG> 


This command displays the value of all elements in array ARR3, in module 
SUB1. ARR3 is a 2 by 3 element array of real numbers. 


DBG> EXAMINE SUB1\ARR3(2,1:3) 


SUB1\ARR3 
(2,1): 15.08000 
(2,295 22.30000 
(2,3): 18.73000 
DBG> 


This command displays the value of the elements in a slice of array 
SUB1\ARR3. The slice includes "columns" 1 to 3 of "row" 2. 


DBG> EXAMINE VALVES. INTAKE.STATUS 
MONITOR\VALVES.INTAKE.STATUS: OFF 
DBG> 


This command displays the value of the nested record component 
VALVES.INTAKE.STATUS in module MONITOR. 


DBG> EXAMINE/SOURCE SWAP 

module MAIN 

47: procedure SWAP (X,Y: in out INTEGER) is 

DBG> 

This command displays the source line in which routine SWAP is declared 
(the location of routine SWAP). 
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DBG> DEPOSIT/ASCII:7 WORK+20 = ‘abcdefg’ 
DBG> EXAMINE/ASCII:7 WORK+20 
DETAT\WORK+20: "“abcdefg" 

DBG> EXAMINE/ASCII:5 WORK+20 
DETAT\WORK+20: "abcde" 

DBG> 


In this example, the DEPOSIT command deposits the entity ‘ abcdefg’ as 
an ASCII string of length 7 bytes into the location that is 20 bytes beyond 
the location denoted by the symbol WORK. The first EXAMINE command 
displays the value of the entity at that location as an ASCII string of length 
7 bytes (abcdefg). The second EXAMINE command displays the value of the 
entity at that location as an ASCII string of length 5 bytes (abcde). 


DBG> EXAMINE/INST MAIN+2 
MAIN\MAIN+02: MOVAL L*MAIN A,R1i1 
DBG> 


This command displays the contents of the location that is 2 bytes beyond the 
location denoted by the symbol MAIN as an instruction (MOVAL). 


DBG> EXAMINE/OPERANDS=FULL .0\%PC 
X\XSSTART+0C: MOVL B*04 (R4),R7 
B*°04(R4) R4 contains X\X$START\M (address 00001054), 
B*04 (00001054) evaluates to X\X$START\K 
(address 00001058), which contains 00000016 
R7 R7 contains 00000000 
DBG> 


This command displays the instruction (MOVL) at the current PC value. The 
/OPERANDS qualifier with the keyword FULL displays the maximum level of 
operand information. 


DBG> SET RADIX HEXADECIMAL 

DBG> EVALUATE/ADDRESS WORKDATA 
000008 6F 

DBG> EXAMINE/SYMBOLIC 0000086F 
MOD3\WORKDATA: 03020100 

DBG> EXAMINE/NOSYMBOLIC 0000086F 
O000086F: 03020100 

DBG> 


In this example, the EVALUATE/ADDRESS command indicates that the 
memory address of variable WORKDATA is 0000086F, hexadecimal. The 
two EXAMINE commands display the value contained at that address using 
the /[NO]JSYMBOL qualifier to control whether the address is symbolized to 
WORKDATA. 


DBG> EXAMINE/HEX FIDBLK 


FDEX1SMAIN\FIDBLK 
CE} s 00000008 
(2): 00000100 
(3): 000000AB 
DBG> 


This command displays the value of the array variable FIDBLK in 
hexadecimal radix. 


12. 
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DBG> EXAMINE/DECIMAL/WORD NEWDATA:NEWDATA+6 
SUB2\NEWDATA: 256 

SUB2\NEWDATA+2: 770 

SUB2\NEWDATA+4: 1284 

SUB2\NEWDATA+6: 1798 

DBG> 


This command displays, in decimal radix, the values of word integer entities 
(2-byte entities) that are in the range of locations denoted by NEWDATA to 
NEWDATA + 6 bytes. 


DBG> EXAMINE/TASK SORT INPUT 
MOD3\SORT_INPUT: %TASK 12 
DBG> 


This command displays the task ID of a task object named SORT_INPUT. 
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Ends a debugging session, or terminates one or more processes of a multiprocess 
program, allowing any application-declared exit handlers to run. 


If used within a command procedure or DO clause and no process is specified, 
exits the command procedure or DO clause at that point. 


EXIT [process-spec], ... ]] 


process-spec 


This parameter applies to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 


Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name 


[%PROCESS_NAME] "process-name" 


%PROCESS_PID process_id 
%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 
process-group-name 
%NEXT_PROCESS 


%PREVIOUS_PROCESS 


%VISIBLE_PROCESS 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’ ) instead 
of quotation marks ("). | 


The VMS process identification number 
(PID, a hexadecimal number). 


The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 


A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


The process after the visible process in 
the debugger’s circular process list. 


The process previous to the visible 
process in the debugger’s circular 
process list. 


The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. 


Description 


Debugger Command Dictionary 
EXIT 


‘The EXIT command is one of the four debugger commands that can be used to 


execute your program (the others are CALL, GO, and STEP). 


Ending a Debugging Session 

To end a debugging session, enter the EXIT command at the debugger prompt 
without specifying any parameters. This causes orderly termination of the 
session: the program’s application-declared exit handlers (if any) are executed, 
the debugger exit handler is executed (closing log files, restoring the screen and 
keypad states, and so on), and control is returned to the command interpreter. 
You cannot then continue to debug your program by entering the DCL commands 
DEBUG or CONTINUE. To restart the debugger, you must run the program 
again. 


Because EXIT runs any application-declared exit handlers, you can set 
breakpoints in such exit handlers, and the breakpoints are triggered upon typing 
EXIT. EXIT can thus be used to debug your exit handlers. 


To end a debugging session without running any application-declared exit 
handlers, use the QUIT command instead of EXIT. 


Using the EXIT Command In Command Procedures and DO Clauses 

When the debugger executes an EXIT command (without any parameters) in 

a command procedure, control returns to the command stream that invoked 

the command procedure. A command stream can be the terminal, an outer 
(containing) command procedure, or a DO clause in a command or screen display 
definition. For example, if the command procedure was invoked from within a DO 
clause, control returns to that DO clause, where the debugger executes the next 
command (if any remain in the command sequence). 


When the debugger executes an EXIT command (without any parameters) in a 
DO clause, it ignores any remaining commands in that clause and displays its 
prompt. 


Terminating Specified Processes 

If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
you can use the EXIT command to terminate specified processes without ending 
the debugging session. The same techniques and behavior apply, whether you 
enter the EXIT command at the prompt or use it within a command procedure or 
DO clause. 


To terminate one or more processes, enter the EXIT command, specifying these 
processes as parameters. This causes orderly termination of the images in these 
processes, executing any application-declared exit handlers associated with these 
images. Subsequently, the specified processes are no longer identified in a SHOW 
PROCESS/ALL display. If any specified processes were on hold, as the result of a 
SET PROCESS/HOLD command, the hold condition is ignored. 


When the specified processes begin to exit, any unspecified process that is not on 
hold begins execution. After execution is started, the way in which it continues 
depends on whether the SET MODE [NO]JINTERRUPT command was entered 
previously. By default (SET MODE INTERRUPT), execution continues until it 
is suspended in any process. At that point, execution is interrupted in any other 
processes that were executing images, and the debugger prompts for input. 
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Examples 
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To terminate specified processes without running any application-declared exit 
handlers or otherwise starting execution, use the QUIT command instead of 
EXIT. 


Related commands: 


@ (Execute Procedure) 

Ctrl/C 

Ctrl/Y 

Ctrl/Z 

QUIT 

SET ABORT_KEY 

SET MODE [NOJINTERRUPT 
SET PROCESS 


1, DBG> EXIT 
$ 


This command ends the debugging session and returns you to DCL level. 


2. JONES 1> EXIT %NEXT_PROCESS, %PROCESS NAME JONES 3, %PROC 5 
JONES_1> 


This command causes orderly termination of three processes of a multiprocess 
program: the process after the visible process on the process list, process 
JONES_3, and process 5. Control is returned to the debugger after the 
specified processes have exited. 


EXITLOOP 


Format 


Parameters 


Description 


Example 
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Exits one or more enclosing FOR, REPEAT, or WHILE loops. 


EXITLOOP [integer] 


integer 
A decimal integer that specifies the number of nested loops to exit from. The 
default is 1. 


Use the EXITLOOP command to exit one or more enclosing FOR, REPEAT, or 
WHILE loops. 


Related commands: 


FOR 
REPEAT 
WHILE 


DBG> WHILE 1 DO (STEP; IF X .GT. 3 THEN EXITLOOP) 


The WHILE 1 command generates an endless loop that executes a STEP 
command with each iteration. After each STEP, the value of X is tested. If X 
is greater than 3, the EXITLOOP command terminates the loop (FORTRAN 
example). | 
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EXPAND 


Format 


Parameters 


Qualifiers 
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Expands or contracts the window associated with a screen display. 


EXPAND [display-name[, ... ]] 


display-name 
Specifies a display to be expanded or contracted. You can specify any of the 
following entities: 


¢ A predefined display: SRC, OUT, PROMPT, INST, REG 
¢ A display previously created with the DISPLAY command 
e A display built-in symbol: 


%CURDISP 
%CURSCROLL 
%NEXTDISP 
%NEXTINST 
%NEXTOUTPUT 
%NEXTSCROLL 
%NEXTSOURCE 


If you do not specify a display, the current scrolling display, as established by the 
SELECT command, is chosen. 


You must specify at least one qualifier. 


/DOWN{:n] 
Moves the bottom border of the display down by n lines (if n is positive) or up by 
n lines (if n is negative). If n is omitted, the border is moved down by 1 line. 


/LEFT[:n] 

Moves the left border of the display to the left by n lines (if n is positive) or to the 
right by n lines (if n is negative). If n is omitted, the border is moved to the left 
by 1 line. 


/RIGHT[:n] 

Moves the right border of the display to the right by n lines (if n is positive) or 
to the left by n lines (if n is negative). If n is omitted, the border is moved to the 
right by 1 line. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Description 


Examples 
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Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 


identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


/UP[:n] 
Moves the top border of the display up by 7 lines (if n is positive) or down by n 
lines (if n is negative). If n is omitted, the border is moved up by 1 line. 


The EXPAND command moves one or more display-window borders according to 
the qualifiers specified (/UP:[n], /DOWN:[n], RIGHT:[n], /LEFT:[n]). 


The EXPAND command does not affect the order of a display on the display 
pasteboard. Depending on the relative order of displays, the EXPAND command 
can cause the specified display to hide or uncover another display or be hidden by 
another display, partially or totally. 


Except for the PROMPT display, any display can be contracted to the point where 
it disappears (at which point it is marked as "removed"). It can then be expanded 
from that point. Contracting a display to the point where it disappears causes it 
to lose any attributes that were selected for it. The PROMPT display cannot be 
contracted or expanded horizontally but can be contracted vertically to a height of 
2 lines. 


A window border can be expanded only up to the edge of the screen. The left 
and top window borders cannot be expanded beyond the left and top edges of the 
display, respectively. The right border can be expanded up to 255 columns from 
the left display edge. The bottom border of a source or instruction display can be 
expanded down only to the bottom edge of the display (to the end of the source 
module or routine’s instructions). A register display cannot be expanded beyond 
its full size. 


See Appendix B for keypad-key definitions associated with the EXPAND 
command. 


Related commands: 


DISPLAY 

MOVE 

SELECT/SCROLL 
(SET,SHOW) TERMINAL 


1. DBG> EXPAND/RIGHT: 6 


This command moves the right border of the current scrolling display to the 
right by 6 columns. 
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2. DBG> EXPAND/UP/RIGHT:-12 OUT2 
This command moves the top border of display OUT2 up by 1 line, and the 
right border to the left by 12 columns. 

3. DBG> EXPAND/DOWN:99 SRC 


This command moves the bottom border of display SRC down to the bottom 
edge of the screen. 
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EXTRACT 


Format 


Parameters 


Qualifiers 
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Saves the contents of screen displays in a file or creates a debugger command 
procedure with all of the commands necessary to re-create the current screen 
state at a later time. 


EXTRACT [display-namefJ, . . . ]] [file-spec] 


display-name 
Specifies a display to be extracted. You can specify any of the following entities: 


e A predefined display: SRC, OUT, PROMPT, INST, REG 
e A display previously created with the DISPLAY command 


You can use the asterisk (*) wildcard character in a display name. Do not specify 
a display name with /ALL. 


file-spec 
Specifies the file to which the information is written. You can specify a logical 
name. 


If you specify /SCREEN_LAYOUT, the default specification for the file is 
SYS$DISK:[ JDBGSCREEN.COM. Otherwise, the default specification is 
SYS$DISK:[ JDEBUG.TXT. 


/ALL 
Extracts all displays. Do not specify a display name with /ALL. Do not specify 
/SCREEN_LAYOUT with /ALL. 


/APPEND 
Appends the information at the end of the file, rather than creating a new file. By 
default, a new file is created. Do not specify /SCREEN_LAYOUT with /APPEND. 


/SCREEN_LAYOUT 

Writes a file that contains the debugger commands describing the current state 
of the screen. This information includes the screen height and width, and the 
position, display kind, and display attributes of every existing display. This file 
can then be executed with the @ (Execute Procedure) command to reconstruct the 
screen at a later time. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 
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Description 


Examples 
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Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


When you use the EXTRACT command to save the contents of a display into a 
file, only those lines that are currently stored in the display’s memory buffer (as 
determined by the /SIZE qualifier on the DISPLAY command) are written to the 
file. 


You cannot extract the PROMPT display into a file. 
Related commands: 


DISPLAY 
SAVE 


1. DBG> EXTRACT SRC 


This command writes all the lines in display SRC into file 
SYS$DISK:[ JDEBUG.TXT. 


2. DBG> EXTRACT/APPEND OUT [JONES.WORK]MYFILE 


This command appends all the lines in display OUT to the end of file 
[JONES.WORK]MYFILE.TXT. 


8. DBG> EXTRACT/SCREEN LAYOUT 


This command writes the debugger commands needed to reconstruct the 
screen into file SYS$DISK:[ ]DBGSCREEN.COM. 


FOR 


Format 


Parameters 
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Executes a sequence of commands while incrementing a variable a specified 
number of times. 


FOR name=expression1 TO expression2 [BY expression3] DO (command; . . . ]) 


name 
Specifies the name of a count variable. 


expression1 
Specifies an integer or enumeration type value. The expression1 and expression2 
parameters must always be of the same type. 


expression2 
Specifies an integer or enumeration type value. The expression1 and expression2 
parameters must always be of the same type. 


expression3 
Specifies an integer. 


command 
Specifies a debugger command. If you specify more than one command, they must 
be separated by semicolons. 


Description | 


Examples 


The behavior of the FOR command depends on the value of the expression3 
parameter. If expression’ is positive, the name parameter is incremented from 
the value of expression1 by the value of expression3 until it is greater than the 
value of expression2. 


If expression3 is negative, name is decremented from the value of expression1 by 
the value of expression3 until it is less than the value of expression2. 


If expression’ is zero, the debugger returns an error message. 
If expression is left out entirely, the debugger assumes it to have the value +1. 
Related commands: 


EXITLOOP 
REPEAT 
WHILE 


1. DBG> FOR I = 10 TO 1 BY -1 DO (EXAMINE A(I)) 


This command examines an array backwards. 


2. DBG> FOR I = 1 TO 10 DO (DEPOSIT A(I) = 0) 


This command initializes an array to zero. 
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Format 


Parameters 


Description 
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Starts or resumes program execution. 


GO _[address-expression] 


address-expression 

Specifies that program execution resume at the location denoted by the address 
expression. If you do not specify an address expression, execution resumes at 
the point of suspension or, in the case of debugger startup, at the image transfer 
address. 


The GO command starts program execution or resumes execution from the point 
at which it is currently suspended. GO is one of the four debugger commands 
that can be used to execute your program (the others are CALL, EXIT, and 
STEP). . 


Specifying an address expression with the GO command can produce unexpected 
results because it alters the normal control flow of your program. For example, 
during a debugging session you can restart execution at the beginning of the 
program by entering the GO %LINE 1 command. However, because the program 
has executed, the contents of some variables might now be initialized differently 
from when you first ran the program. 


If an exception breakpoint is triggered (resulting from a SET BREAK 
/EXCEPTION or a STEP/EXCEPTION command), execution is suspended 
before any application-declared condition handler is invoked. If you then resume 
execution with the GO command, the behavior is as follows: 


¢ Entering a GO command to resume execution from the current location causes 
the debugger to resignal the exception. This use of the GO command enables 
you to observe which application-declared handler, if any, next handles the 
exception. | 


¢ Entering a GO command to resume execution from a location other than the 
current location inhibits the execution of any application-declared handler for 
that exception. 


If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
note the following additional points: 


¢ The GO command is executed in the context of the visible process, but 
images in any other processes that are not on hold (through a SET PROCESS 
/HOLD command) are also allowed to execute. If you use the DO command 
to broadcast a GO command to one or more processes, the GO command 
is executed in the context of each specified process that is not on hold, but 
images in any other processes that are not on hold are also allowed to execute. 
In all cases, a hold condition in the visible process is ignored. 


Examples 
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GO 


After execution is started, the way in which it continues depends on whether 
the SET MODE [NO]JINTERRUPT command was entered. By default (SET 
MODE INTERRUPT), execution continues until it is suspended in any 
process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 


Related commands: 


CALL 

DO 

EXIT 

SET BREAK 

SET MODE [NOJINTERRUPT 
SET PROCESS 

SET STEP 

SET TRACE 

SET WATCH 

STEP 


DBG> GO 


SDEBUG-I-EXITSTATUS, is ‘SSYSTEM-S-NORMAL, normal successful 
completion’ 
DBG> 


This command starts program execution, which then completes successfully. 


DBG> SET BREAK RESTORE 
DBG> GO 


break at routine INVENTORY\RESTORE 
137: procedure RESTORE; 
DBG> GO 


This SET BREAK command sets a breakpoint on routine RESTORE. The 
first GO command starts program execution, which is then suspended at 

the breakpoint on routine RESTORE. The second GO command resumes 

execution from the breakpoint. 


DBG> GO $LINE 42 


This command resumes program execution at line 42 of the module in which 
execution is currently suspended.. 
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Format 


Parameters 


Description 


Example 
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Displays online help on debugger commands and selected topics. 


HELP topic [subtopic [ .. . ]] 


topic 

Specifies the name of a debugger command or topic about which you want help. 
You can specify the asterisk (*) wildcard character, either singly or within a 
name. 


subtopic 

Specifies a subtopic, qualifier, or parameter about which you want further 
information. You can specify the asterisk wildcard (*), either singly or within a 
name. 


The debugger’s online help facility provides the following information about any 
debugger command: a description of the command, format of the command, 
parameters that can be specified with the command, and qualifiers that can be 
specified with the command. 


To obtain information about a particular qualifier or parameter, specify it as a 
subtopic. If you want information about all qualifiers, specify "qualifier" as a 
subtopic. If you want information about all parameters, specify "parameter" as a 
subtopic. If you want information about all parameters, qualifiers, and any other 
subtopics related to a command, specify * as a subtopic. 


In addition to help on commands, you can get online help on various topics such 
as screen features, keypad mode, and so on. Topic keywords are listed along with 
the commands when you type HELP. 


Type HELP Release_Notes for information about any incompatibilities between 
the current release of the debugger and previous releases. Type HELP New_ 
Features for summary information about new features with this release of the 
debugger. 


For help on the predefined keypad-key functions, see Appendix B. 


DBG> HELP GO 


This command displays help for the GO command. 


IF 


Format 


Parameters 


Description 


Example 
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Executes a sequence of commands if a language expression (Boolean expression) 
is evaluated as true. 


IF Boolean-expression THEN (command; ... ]) [ELSE (command; . . . ])] 


Boolean-expression 
Specifies a language expression that evaluates as a Boolean value (true or false) 
in the currently set language. 


command 
Specifies a debugger command. If you specify more than one command, you must 
separate them with semicolons (;). 


The IF command evaluates a Boolean expression. If the value is true (as defined 
in the current language), the debugger command list in the THEN clause is . 
executed. If the expression is false, the command list in the ELSE clause is 
executed (if it is present). 


Related commands: 


EXITLOOP 
FOR 
REPEAT 
WHILE 


DBG> SET BREAK R DO (IF X .LT. 5 THEN (GO) ELSE (EXAMINE X)) 


This command causes the debugger to suspend program execution at location R 
(a breakpoint) and then resume program execution if the value of X is less than 5 
(FORTRAN example). If the value of X is 5 or more, the value of X is displayed. 
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Format 


Parameters 


Qualifiers 
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Moves a screen display vertically or horizontally across the screen. 
MOVE §[display-name{, .. . J] 


display-name 
Specifies a display to be moved. You can specify any of the following entities: 


¢ A predefined display: SRC, OUT, PROMPT, INST, REG 
e A display previously created with the DISPLAY command 
e A display built-in symbol: 


%CURDISP 
%CURSCROLL 
%NEXTDISP 
%NEXTINST 
%NEXTOUTPUT 
%NEXTSCROLL 
%NEXTSOURCE 


If you do not specify a display, the current scrolling display, as established by the 
SELECT command, is chosen. 


You must specify at least one qualifier. 


/DOWN[:n] 
Moves the display down by n lines (if n is positive) or up by n lines (if n is 
negative). Ifn is omitted, the display is moved down by 1 line. 


/LEFT[:n] 
Moves the display to the left by n lines (if n is positive) or right by n lines (if n is 
negative). If n is omitted, the display is moved to the left by 1 line. 


/RIGHT[:n] 
Moves the display to the right by n lines (if n is positive) or left by n lines (if n is 
negative). If is omitted, the display is moved to the right by 1 line. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Description 


Examples 
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Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 

PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


/UP[:n] 
Moves the display up by 7 lines (if n is positive) or down by n lines (if n is 
negative). Ifn is omitted, the display is moved up by 1 line. 


For each display specified, the MOVE command simply creates a window of 
the same dimensions elsewhere on the screen and maps the display to it, while 
maintaining the relative position of the text within the window. 


The MOVE command does not change the order of a display on the display 
pasteboard. Depending on the relative order of displays, the MOVE command 
can cause the display to hide or uncover another display or be hidden by another 
display, partially or totally. 


A display can be moved only up to the edge of the screen. 
See Appendix B for keypad-key definitions associated with the MOVE command. 
Related commands: 


DISPLAY 

EXPAND 
SELECT/SCROLL 
(SET,SSHOW) TERMINAL 


1. DBG> MOVE/LEFT 


This command moves the current scrolling display to the left by 1 column. 


2. DBG> MOVE/UP:3/RIGHT:5 NEW OUT 


This command moves display NEW_OUT up by 3 lines and to the right by 5 
columns. 
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Format 


Parameters 
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Ends a debugging session, or terminates one or more processes of a multiprocess 
program (like EXIT), but without allowing any application-declared exit handlers 
to run. 


If used within a command procedure or DO clause and no process is specified, 
exits the command procedure or DO clause at that point. 


QUIT [process-spec], .. . ]] 


process-spec 
This parameter applies to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 


Specifies a process. Use any of the following forms: 


[(%PROCESS_NAME] process-name The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


[%PROCESS_NAME] "process-name" The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’) instead 
of quotation marks("). 


%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 


%PROCESS_NUMBER proc-number The number assigned to a process 

(or %PROC proc-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 
%PREVIOUS_PROCESS The process previous to the visible 


process in the debugger’s circular 
process list. 

%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. 


Description 
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The QUIT command is like the EXIT command, except that QUIT does not cause 
your program to execute and, therefore, does not execute any application-declared 
exit handlers in your program. 


Ending a Debugging Session 

To end a debugging session, enter the QUIT command at the debugger prompt 
without specifying any parameters. This causes orderly termination of the 
session: the debugger exit handler is executed (closing log files, restoring the 
screen and keypad states, and so on), and control is returned to the command 
interpreter. You cannot then continue to debug your program by entering the 
DCL commands DEBUG or CONTINUE. To restart the debugger, you must run 
the program again. 


Using the QUIT Command in Command Procedures and DO Clauses 

When the debugger executes a QUIT command (without any parameters) in 

a command procedure, control returns to the command stream that invoked 

the command procedure. A command stream can be the terminal, an outer 
(containing) command procedure, or a DO clause in a command or screen display 
definition. For example, if the command procedure was invoked from within a DO 
clause, control returns to that DO clause, where the debugger executes the next 
command (if any remain in the command sequence). 


When the debugger executes a QUIT command (without any parameters) in a 
DO clause, it ignores any remaining commands in that clause and displays its 
prompt. 


Terminating Specified Processes 

If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
you can use the QUIT command to terminate specified processes without ending 
the debugging session. The same techniques and behavior apply, whether you 
enter the QUIT command at the prompt or use it within a command procedure or 
DO clause. 


To terminate one or more processes, enter the QUIT command, specifying these 
processes as parameters. This causes orderly termination of the images in these 
processes without executing any application-declared exit handlers associated 
with these images. Subsequently, the specified processes are no longer identified 
in a SHOW PROCESS/ALL display. 


In contrast to the EXIT command, the QUIT command does not cause any process 
to start execution. 


Related commands: 


@ (Execute Procedure) 
Ctrl/C 

Ctrl/Y 

Ctrl/Z 

EXIT 

SET ABORT_KEY 
SET PROCESS 
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DBG> QUIT 
$ 


This command, when entered from the prompt, ends the debugging session 
and returns you to DCL command level. 


JONES _1> QUIT %NEXT PROCESS, %PROCESS NAME JONES 3, %PROC 5 
JONES” 1> 


This command causes orderly termination of three processes of a multiprocess 
program: the process after the visible process on the process list, process 
JONES_3, and process 5. Control is returned to the debugger after the 
specified processes have exited. 


REPEAT 


Format 


Parameters 


Description 


Example 
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Executes a sequence of commands a specified number of times. 


REPEAT language-expression DO (command; . . . ]) 


language-expression 
Denotes any expression in the currently set language that evaluates to a positive 
integer. 


command 
Specifies a debugger command. If you specify more than one command, they must 
be separated by semicolons. 


The REPEAT command is a simple form of the FOR command. The REPEAT 
command executes a sequence of commands repetitively a specified number of 
times, without providing the options for establishing count parameters that the 
FOR command does. 


Related commands: 


EXITLOOP 
FOR 
WHILE 


DBG> REPEAT 10 DO (EXAMINE Y; STEP) 


This command line sets up a loop that issues a sequence of two commands 
(EXAMINE Y, then STEP) 10 times. 
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SAVE 


Format 


Parameters 


Qualifiers 
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Preserves the contents of an existing screen display in a new display. 
SAVE old-display AS new-display [, ... ] 


old-display 
Specifies the display whose contents are saved. You can specify any of the 
following entities: 


¢ A predefined display: SRC, OUT, PROMPT, INST, REG 
¢ Adisplay previously created with the DISPLAY command 
¢ A display built-in symbol: 


%CURDISP | 
%CURSCROLL 
%NEXTDISP 
%NEXTINST 
%NEXTOUTPUT 
%NEXTSCROLL 
%NEXTSOURCE 


new-display 
Specifies the name of the new display to be created. This new display then 
receives the contents of the old-disp display. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 


identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


Description 


Example 
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The SAVE command enables you to save a "snapshot" copy of an existing display 
in a new display for later reference. The new display is created with the same 
text contents as the existing display. In general, the new display is given all the 
attributes or characteristics of the old display except that it is removed from the 
screen and is never automatically updated. You can later recall the saved display 
to the terminal screen with the DISPLAY command. 


When you use the SAVE command, only those lines that are currently stored 
in the display’s memory buffer (as determined by the /SIZE qualifier on the 
DISPLAY command) are stored in the saved display. However, in the case of 
a saved source or instruction display, you can also see any other source lines 
associated with that module or any other instructions associated with that 
routine (by scrolling the saved display). 


You cannot save the PROMPT display. 
Related commands: 


DISPLAY 
EXITLOOP 


DBG> SAVE REG AS OLDREG 


This command saves the contents of the display named REG into the newly 
created display named OLDREG. 
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Scrolls a screen display to make other parts of the text visible through the display 
window. 


SCROLL  [display-name] 


display-name 
Specifies a display to be scrolled. You can specify any of the following entities: 


e A predefined display: SRC, OUT, PROMPT, INST, REG 
e A display previously created with the DISPLAY command 
e A display built-in symbol: 


%CURDISP 
%CURSCROLL 
%NEXTDISP 
YNEXTINST 
%NEXTOUTPUT 
%NEXTSCROLL 
%NEXTSOURCE 


If you do not specify a display, the current scrolling display, as established by the 
SELECT command, is chosen. 


/BOTTOM 
Scrolls down to the bottom of the display’s text. 


/DOWN:[n] 

Scrolls down over the display’s text by n lines to reveal text further down in the 
display. If n is omitted, the display is scrolled by approximately 3/4 of its window 
height. 


/LEFT:{[n] 

Scrolls left over the display’s text by n columns to reveal text beyond the left 
window border. You cannot scroll past column 1. If n is omitted, the display is 
scrolled left by 8 columns. 


/RIGHT[:n] 

Scrolls right over the display’s text by n columns to reveal text beyond the right 
window border. You cannot scroll past column 255. If n is omitted, the display is 
scrolled right by 8 columns. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Description 


Examples 
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Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


/TOP 
Scrolls up to the top of the display’s text. 


/UP[:n] 

Scrolls up over the display’s text by n lines to reveal text further up in the 
display. If n is omitted, the display is scrolled by approximately 3/4 of its window 
height. 


The SCROLL command moves a display up, down, right, or left relative to its 
window so that various parts of the display text can be made visible through the 
window. 


Use the SELECT/SCROLL command to select the target display for the SCROLL 
command (the current scrolling display). 


See Appendix B for keypad-key definitions associated with the SCROLL 
command. 


Related command: SELECT. 


1. DBG> SCROLL/LEFT 


This command scrolls the current scrolling display to the left by 8 columns. 


2. DBG> SCROLL/UP:4 ALPHA 


This command scrolls display ALPHA 4 lines up. 
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Searches the source code for a specified string and displays source lines that 
contain an occurrence of the string. 


SEARCH [range] [string] 


range 


Specifies a program region to be searched. Use any of the following formats: 


mod-name 
mod-name\line-num 


mod-name\line-numiline-num 


line-num 


line-num:line-num 


null (no entry) 


string 


Searches the specified module from line 0 to the 
end of the module. 


Searches the specified module from the specified 
line number to the end of the module. 


Searches the specified module from the line 
number specified on the left of the colon to the 
line number specified on the right. 


Uses the current scope to find a module and 
searches that module from the specified line 
number to the end of the module. The current 
scope is that established by a previous SET 
SCOPE command, or the PC scope if no SET 
SCOPE command was entered. If you specify 
a scope search list with the SET SCOPE 
command, the debugger searches only the 
module associated with the first named scope. 


Uses the current scope to find a module and 
searches that module from the line number 
specified on the left of the colon to the line 
number specified on the right. The current 
scope is that established by a previous SET 
SCOPE command, or the PC scope if no SET 
SCOPE command was entered. If you specify 
a scope search list with the SET SCOPE 
command, the debugger searches only the 
module associated with the first named scope. 


Searches the same module as that from which 
a source line was most recently displayed (as _ 
a result of a TYPE, EXAMINE/SOURCE, or 
SEARCH command, for example), beginning at 
the first line following the line most recently 
displayed and continuing to the end of the 
module. 


Specifies the source code characters for which to search. If you do not specify a 
string, the string specified in the last SEARCH command, if any, is used. 


Qualifiers 


Description 
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You must enclose the string in quotation marks (") or apostrophes (’ ) under the 
following conditions: 


e The string has any leading or ending space or tab characters 
¢ The string contains an embedded semicolon 
e The range parameter is null 


If the string is enclosed in quotation marks, use two consecutive quotation 
marks ("") to indicate an enclosed quotation mark. If the string is enclosed 
in apostrophes, use two consecutive apostrophes (’’) to indicate an enclosed 
apostrophe. 


/ALL 
Specifies that the debugger search for all occurrences of the string in the specified 
range and display every line containing an occurrence of the string. 


[IDENTIFIER 

Specifies that the debugger search for an occurrence of the string in the specified 
range but display the string only if it is not bounded on either side by a character 
that can be part of an identifier in the current language. 


/NEXT 

Specifies that the debugger search for the next occurrence of the string in the 
specified range and display only the line containing this occurrence. This is the 
default. 


/STRING 

Specifies that the debugger search for and display the string as specified, and not 
interpret the context surrounding an occurrence of the string, as it does in the 
case of /IDENTIFIER. This is the default. 


‘The SEARCH command displays the lines of source code that contain an 


occurrence of a specified string. 


If you specify a module name with the SEARCH command, that module must be 
set. To determine whether a particular module is set, use the SHOW MODULE 
command, then use the SET MODULE command, if necessary. — 


SEARCH command qualifiers determine whether the debugger: (1) searches 
for all occurrences (/ALL) of the string or only the next occurrence (/NEXT); and 
(2) displays any occurrence of the string (/STRING) or only those occurrences in 
which the string is not bounded on either side by a character that can be part of 
an identifier in the current language (IDENTIFIER). 


If you plan to enter several SEARCH commands with the same qualifier, you 
can first use the SET SEARCH command to establish a new default qualifier 
(for example, SET SEARCH ALL makes the SEARCH command behave like 
SEARCH/ALL). Then you do not have to use that qualifier with the SEARCH 
command. You can override the current default qualifiers for the duration of a 
single SEARCH command by specifying other qualifiers. 


CD-115 


Debugger Command Dictionary 


SEARCH 


Examples 


CD-116 


Related commands: 


(SET,SHOW) LANGUAGE 
(SET,SHOW) MODULE 
(SET,SSHOW) SCOPE 
(SET,SSHOW) SEARCH 


DBG> SEARCH/STRING/ALL 40:50 D 
module COBOLTEST 


40: 02 D2N COMP=-2 VALUE -234560000000. 

41: 02 D COMP-2 VALUE 222222.33. 

42: 02 DN COMP-2 VALUE -222222.333333. 

47: 02 DRO COMP-2 VALUE 0.1. 

48: 02 DR5 COMP-2 VALUE 0.000001. 

49:°02 DR10 COMP-2 VALUE 0.00000000001. 

50: 02 DR15 COMP-2 VALUE 0.0000000000000001. 
DBG> 


This command searches for all occurrences of the letter D in lines 40 to 50 of 
the module COBOLTEST, the module that is in the current scope. 


DBG> SEARCH/IDENTIFIER/ALL 40:50 D 
module COBOLTEST 

41: 02 D COMP-2 VALUE 222222.33. 
DBG> 


This command searches for all occurrences of the letter D in lines 40 to 50 
of the module COBOLTEST. The debugger displays the only line where the 
letter D (the search string) is not bounded on either side by a character that 
can be part of an identifier in the current language. 


DBG> SEARCH/NEXT 40:50 D 
module COBOLTEST 

40: 02 D2N COMP-2 VALUE -234560000000. 
DBG> 


This command searches for the next occurrence of the letter D in lines 40 to 
50 of the module COBOLTEST. 


DBG> SEARCH/NEXT 
module COBOLTEST 

ale 02 D COMP-2 VALUE 222222.33. 
DBG> 


This command searches for the next occurrence of the letter D. The debugger 
assumes D to be the search string because D was the last one entered and no 
other search string was specified. 


DBG> SEARCH 43 D 
module COBOLTEST 

47: 02 DRO COMP-2 VALUE 0.1. 
DBG> 


This command searches for the next occurrence (by default) of the letter D, 
starting with line 48. 


SELECT 


Format 


Parameters 


Qualifiers 
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Selects a screen display as the current error, input, instruction, output, program, 
prompt, scrolling, or source display. 


SELECT  [display-name] 


display-name 
Specifies the display to be selected. You can specify any one of the following, with 
the restrictions noted in the qualifier descriptions: 


¢ A predefined display (SRC, OUT, INST, REG, and PROMPT) 
e A display previously created with the DISPLAY command 
¢ A display built-in symbol: 


%CURDISP 
%CURSCROLL 
%NEXTDISP 
%NEXTINST 
%NEXTOUTPUT 
%NEXTSCROLL 
%NEXTSOURCE 


If you omit this parameter and do not specify a qualifier, you "unselect" the 
current scrolling display (no display then has the scrolling attribute). If you 
omit this parameter but specify a qualifier (INPUT, /SOURCE, and so on), you 
unselect the current display with that attribute (see the qualifier descriptions). 


/ERROR 

If you specify a display, selects it as the current error display. This causes all 
debugger diagnostic messages to go to that display. The display specified must be 
either an output display or the PROMPT display. 


If you do not specify a display, the PROMPT display is selected as the current 
error display. 


By default, the PROMPT display has the error attribute. 
/INPUT | 
If you specify a display, selects it as the current input display. This causes that 


display to echo debugger input (which always appears in the PROMPT display). 
The display specified must be an output display. 


If you do not specify a display, the current input display is unselected and 
debugger input is not echoed to any display (debugger input appears only in the 
PROMPT display). 


By default, no display has the input attribute. 
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/INSTRUCTION 

If you specify a display, selects it as the current instruction display. This 
causes the output of all EXAMINE/AINSTRUCTION commands to go to that 
display. The display specified must be an instruction display. 


If you do not specify a display, the current instruction display is unselected and 
no display has the instruction attribute. 


By default, for all languages except MACRO, no display has the instruction 
attribute. If the language is set to MACRO, the INST display has the instruction 
attribute by default. 


/OUTPUT 

If you specify a display, selects it as the current output display. This causes 
debugger output that is not already directed to another display to go to that 
display. The display specified must be either an output display or the PROMPT 
display. ; 


If you do not specify a display, the PROMPT display is selected as the current 
output display. 


By default, the OUT display has the output attribute. 


/PROGRAM 

If you specify a display, selects it as the current program display. This causes 
the debugger to try to force program input and output to that display. Currently, 
only the PROMPT display can be specified. 


If you do not specify a display, the current program display is unselected and 
program input and output are no longer forced to the specified display. 


By default, the PROMPT display has the program attribute, except on 
workstations, where the program attribute is unselected. 


/PROMPT 
Selects the specified display as the current prompt display. This is where 
the debugger prompts for input. Currently, only the PROMPT display can be 


- specified. Moreover, you cannot unselect the PROMPT display (the PROMPT 


display always has the prompt attribute). 


/SCROLL 

If you specify a display, selects it as the current scrolling display. This is the 

default display for the SCROLL, MOVE, and EXPAND commands. Although any 
display can have the scroll attribute, you can use only the MOVE and EXPAND 

commands (not the SCROLL command) with the PROMPT display. 


If you do not specify a display, the current scrolling display is unselected and no 
display has the scroll attribute. 


By default, for all languages except MACRO, the SRC display has the scroll 
attribute. If the language is set to MACRO, the INST display has the scroll 
attribute by default. 


If no qualifier is specified, /SCROLL is assumed by default. 


/SOURCE 

If you specify a display, selects it as the current source display. This causes 
the output of all TYPE and EXAMINE/SOURCE commands to go to that display. 
The display specified must be a source display. 


Description 
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If you do not specify a display, the current source display is unselected and no 
display has the source attribute. 


By default, for all languages except MACRO, the SRC display has the source 
attribute. If the language is set to MACRO, no een has the source attribute 
by default. 


/SUFFIX[=process-identifier-type] 


Applies to a multiprocess debugging configuration (when DBG$PROCESS has the - 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


Attributes are used to select the current scrolling display and to direct various 
types of debugger output to particular displays. This gives you the option of 
mixing or isolating different types of information, such as debugger input, output, 
diagnostic messages, and so on in scrollable displays. 


You use the SELECT command with one or more qualifiers (ERROR, /SOURCE, 
and so on) to assign one or more corresponding attributes to a display. If you do 
not specify a qualifier, the /SCROLL qualifier is assumed by default. 


If you use the SELECT command without specifying a display name, in general 
the attribute assignment indicated by the qualifier is canceled (unselected). To 
reassign display attributes you must use another SELECT command. See the 
individual qualifier descriptions for details. 


See Appendix B for PEYDAC REY definitions associated with the SELECT 
command. 


Related commands: 


DISPLAY 
EXPAND 

MOVE 

SCROLL 

SHOW SELECT 


CD-119 


Debugger Command Dictionary 


SELECT 


Examples 


CD-120 


DBG> SELECT/SOURCE/SCROLL SRC2 


This command selects display SRC2 as the current source and scrolling 
display. 


DBG> SELECT/INPUT/ERROR OUT 


This command selects display OUT as the current input and error display. 
This causes debugger input, debugger output (assuming OUT is the current 
output display), and debugger diagnostic messages to be logged in the OUT 
display in the correct sequence. 


DBG> SELECT/SOURCE 


This command unselects (deletes the source attribute from) the currently 
selected source display. The output of a TYPE or EXAMINE/SOURCE 
command then goes to the currently selected output display. 
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SET ABORT_KEY 


Format 


Parameters 


Description 


Example 


Assigns the debugger’s abort function to another Ctrl-key sequence. By default, 
Ctrl/C does the abort function. 


SET ABORT_KEY = CTRL character 


character 
Specifies the key you press while holding down the Ctrl key. You can specify any 
alphabetic character. 


By default, the Ctrl/C sequence, when entered within a debugging session, aborts 
the execution of a debugger command and interrupts program execution. The 
SET ABORT_KEY command enables you to assign the abort function to another 
Ctrl-key sequence. This might be necessary if your program has a Ctrl/C AST 
service routine enabled. 


Many Ctrl-key sequences have VMS predefined functions, and the SET ABORT_ 
KEY command enables you to override such definitions (see the VM@S DCL 
Concepts Manual). Some of the Ctrl-key characters not used by the VMS 
operating system are G, K, N, and P. 


The SHOW ABORT_KEY command identifies the Ctrl-key sequence currently in 
effect for the abort function. 


Do not use Ctrl/Y from within a debugging session. Always use either Ctrl/C 
or an equivalent Ctrl-key sequence established with the SET ABORT_KEY 
command. 


Related commands: 


Ctrl/C 
Ctrl/Y 
SHOW ABORT_KEY 


DBG> SHOW ABORT KEY 
Abort Command Key is CTRL _C 
DBG> GO 


DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 
1000: 0 

1004: 
1008: 
1012: 


0 
0 
0 
1016: 0 
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CtrvC} 

SDEBUG-W-ABORTED, command aborted by user request 
DBG> SET ABORT KEY = CTRL P 

DBG> GO 


CtrvP | 

DBG> EXAMINE/BYTE 1000:101000 !should have typed 1000:1010 
1000: 
1004: 
1008: 
1012: 
1016: 
SDEBUG-W-ABORTED, command aborted by user request 
DBG> 


Lan ae ae a a) 


This sequence of commands shows the following entities: 
¢ Use of the (default) Ctrl/C sequence to perform the abort function. 


¢ Use of the SET ABORT_KEY command to reassign the abort function to the 
Ctri/P sequence. 


SET ATSIGN 


Format 


Parameters 


Description 


Example 
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Establishes the default file specification that the debugger uses when searching 
for command procedures. 


SET ATSIGN _ file-spec 


file-spec 

Specifies any part of a VMS file specification (for example, a directory name or a 
file type) that the debugger is to use by default when searching for a command 
procedure. If you do not supply a full file specification, the debugger assumes 
SYS$DISK:[]DEBUG.COM as the default file specification for any missing field. 


You can specify a logical name that translates to a search list. In this case, the - 
debugger processes the file specifications in the order they appear in the search 
list until the command procedure is found. 


When you invoke a command procedure during a debugging session, the debugger, 
by default, assumes that its file specification is SYS$DISK:[ ]DEBUG.COM. The 
SET ATSIGN command enables you to override this default. 


Related commands: 


@ (Execute Procedure) 
SHOW ATSIGN 


DBG> SET ATSIGN USER: [JONES.DEBUG] .DBG 
DBG> @TEST 


In this example, when the user invokes @TEST, the debugger looks for the file 
TEST.DBG in USER:[JONES.DEBUG]. 
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Establishes a breakpoint at the location denoted by an address expression, at 
instructions of a particular class, or at the occurrence of specified events. 


SET BREAK [address-expression[, . . . ]] [WHEN(conditional-expression)] 
[DO(command[; .. . ])] 


address-expression 

Specifies an address expression (a program location) at which a breakpoint is 

to be set. With high-level languages, this is typically a line number, a routine 
name, or a label, and can include a pathname to specify the entity uniquely. 
More generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the operators that can 
be used in address expressions. 


Do not specify the asterisk (*) wildcard character. Do not specify an address 
expression with any of the following qualifiers: 


/ACTIVATING 

/BRANCH 

/CALL 

/EXCEPTION 
AINSTRUCTION[=(opcode ... )] 
INTO 

/[NO]JSB 

/LINE 

/OVER 

/[NO|JSHARE 
/[NO]SYSTEM 
/TERMINATING 
/VECTOR_INSTRUCTION 


The /MODIFY and /RETURN qualifiers are used with specific kinds of address 
expressions. 


If you specify a memory address or an address expression whose value is not 

a symbolic location, check (with the EXAMINE command) that an instruction 
actually begins at the byte of memory so indicated. If an instruction does not 
begin at this byte, a run-time error can occur when an instruction including that 
byte is executed. When you set a breakpoint by specifying an address expression 
whose value is not a symbolic location, the debugger does not verify that the 
location specified marks the beginning of an instruction. CALLS and CALLG 
routines start with an entry mask. 


conditional-expression 

Specifies a conditional expression in the currently set language that is to be 
evaluated when execution reaches the breakpoint. If the expression is true, 
break action occurs, and the debugger reports that a break has occurred. If the 
expression is false, break action does not occur. In this case, a report is not 


Qualifiers 


Debugger Command Dictionary 
SET BREAK 


issued, the commands specified by the DO clause are not executed, and program 
execution is continued. 


command 
Specifies a debugger command to be executed as part of the DO clause when 
break action is taken. 


/ACTIVATING 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS),. 


Causes the debugger to break when a new process comes under debugger control. 
The debugger prompt is displayed when the first process comes under debugger 
control. This enables you to enter debugger commands before the program has 
started execution. Do not specify an address expression with /ACTIVATING. See 
also /TERMINATING. 


/AFTER:n 

Specifies that break action not be taken until the nth time the designated 
breakpoint is encountered (n is a decimal integer). Thereafter, the breakpoint 
occurs every time it is encountered provided that conditions in the WHEN clause 
(if specified) are true. The SET BREAK/AFTER:1 command has the same effect 
as the SET BREAK command. 


/BRANCH 

Causes the debugger to break on every branch instruction encountered during 
program execution. Do not specify an address expression with /BRANCH. See 
also /INTO and /OVER. 


CALL 

Causes the debugger to break on every call instruction encountered during 
program execution, including the RET instruction. Do not specify an address 
expression with /CALL. See also /INTO and /OVER. 


/EVENT=event-name 

Causes the debugger to break on the specified event (if that event is defined and 
detected by the current event facility). If you specify an address expression with 
/EVENT, causes the debugger to break whenever the specified event occurs for 
that address expression. You cannot specify an address expression with certain 
event names. 


Event facilities are available for programs that call Ada or SCAN routines or 
that use DECthreads services. Use the SHOW EVENT_FACILITY command to 
identify the current event facility and the associated event names. 


/EXCEPTION 

Causes the debugger to break whenever an exception is signaled. The break 
action occurs before any application-declared exception handlers are invoked. Do 
not specify an address expression with /EXCEPTION. 


As a result of a SET BREAK/EXCEPTION command, whenever your program 
generates an exception, the debugger suspends program execution, reports 
the exception, and displays its prompt. When you resume execution from an 
exception breakpoint, the behavior is as follows: 
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e If you enter a GO command without an address-expression parameter, the 
exception is resignaled, thus allowing any application-declared exception 
handler to execute. 


¢ Ifyou enter a GO command with an address-expression parameter, program 
execution continues at the specified location, thus inhibiting the execution of 
any application-declared exception handler. 


¢ If you enter a STEP command, the debugger steps into any application- 
declared exception handler. If there is no application-declared handler for 
that exception, the debugger resignals the exception. 


¢ Ifyou enter a CALL command, the routine specified is executed. If a routine 
is called with the CALL command directly after an exception breakpoint has 
been triggered, no breakpoints, tracepoints, or watchpoints set within that 
routine are triggered. However, they are triggered if the CALL command is 
given at another time. 


/INSTRUCTION[=(opcodef[, . . . ])] 

If you do not specify an opcode, causes the debugger to break on every instruction 
encountered during program execution. If you specify one or more opcodes, causes | 
the debugger to break on every instruction whose opcode is in the list. 


Do not specify an address expression with this qualifier. If you specify a vector 
instruction, do not include an instruction qualifier (/U, /V, /M, /0, or /1) with the 
instruction mnemonic. See also /INTO and /OVER. 


/INTO 
Applies only to breakpoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: 


/BRANCH 

/CALL 
AINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 


When used with those qualifiers, causes the debugger to break at the specified 
points within called routines (as well as within the routine in which execution 
is currently suspended). The /INTO qualifier is the default behavior and is the 
opposite of /OVER. 


When using /INTO, you can further qualify the break action with the /[NO]JSB, 
/[NOJSHARE, and /[NO]SYSTEM qualifiers. 


/JSB 

/NOJSB 

Qualifies INTO. Use /[NO]JJSB only with /INTO and one of the following 
qualifiers: 


/BRANCH 

/CALL 
JINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 
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The /JSB qualifier is the default for all languages except DIBOL. The /JSB 
qualifier permits the debugger to break within routines that are called by the 
JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) specifies 
that breakpoints not be set within routines called by JSB instructions. In DIBOL, 
application-declared routines are called by the CALL instruction and DIBOL 
run-time library routines are called by the JSB instruction. Do not specify an 
address expression with /[NO]JSB. 


/LINE . 

Causes the debugger to break on the beginning of each source line encountered 
during program execution. Do not specify an address expression with /LINE. See 
also /INTO and /OVER. 


/MODIFY: 

Causes the debugger to break on every instruction that writes to and modifies the 
value of the location indicated by the address expression. The address expression 
is typically a variable name. 


The SET BREAK/MODIFY command acts exactly like a SET WATCH command 
and operates under the same restrictions. 


If you specify an absolute address for the address expression, the debugger might 
not be able to associate the address with a particular data object. In this case, the 
debugger uses a default length of 4 bytes. You can change this length, however, 
by setting the type to either WORD (SET TYPE WORD, which changes the 
default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default 
length to 1 byte). SET TYPE LONGWORD restores the default length of 4 bytes. 


/OVER 
Applies only to breakpoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: . 


/BRANCH 

/CALL, 
/AINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 


When used with those qualifiers, causes the debugger to break at the specified 
points only within the routine in which execution is currently suspended (not 
within called routines). The /OVER qualifier is the opposite of /INTO (the default 
behavior). 


/RETURN 

Causes the debugger to break on the RET (return) instruction of the routine 
associated with the specified address expression (which can be a routine name, 
line number, and so on). This qualifier can only be applied to routines called 
with a CALLS or CALLG instruction; it cannot be used with JSB routines. 
Breaking on the RET instruction enables you to inspect the local environment (for 
example, obtain the values of local variables) before the RET instruction deletes 
the routine’s call frame from the call stack. 


For this qualifier, the address-expression parameter is an instruction address 
within a CALLS or CALLG routine. It can simply be a routine name, in which 
case it specifies the routine start address. However, you can also specify another 
location in a routine, so you can see only those returns that are taken after a 
certain code path is followed. 
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A SET BREAK/RETURN command cancels a previous SET BREAK command if 
the same address expression is specified. 


/SHARE (default) 

/NOSHARE 

Qualifies INTO. Use /[NO]JSHARE only with /INTO and one of the following 
qualifiers: 


/JINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 


The /SHARE qualifier permits the debugger to break within shareable image 
routines as well as other routines. The /NOSHARE qualifier specifies that 
breakpoints not be set within shareable images. Do not specify an address 
expression with /[NO]JSHARE. 


/SILENT 

/NOSILENT (default) 

Controls whether the "break ... " message and the source line for the current 
location are displayed at the breakpoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
the source line are not displayed. The /SILENT qualifier overrides /SOURCE. See 
also SET STEP [NOJSOURCE. 


/SOURCE (default) 

/NOSOURCE 
Controls whether the source line for the current location is displayed at the 
breakpoint. The /SOURCE qualifier specifies that the source line is displayed. 
The /NOSOURCE qualifier specifies that no source line is displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NOJSOURCE. 


/SYSTEM (default) 

/INOSYSTEM 

Qualifies INTO. Use /[NOJSYSTEM only with /INTO and one of the following 
qualifiers: 


/BRANCH 

/CALL 
AINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 


The /SYSTEM qualifier permits the debugger to break within system routines 
(P1 space) as well as other routines. The /NOSYSTEM qualifier specifies that 
breakpoints not be set within system routines. Do not specify an address 
expression with /LNO]SYSTEM. 


‘TEMPORARY 
Causes the breakpoint to disappear after it is triggered (the breakpoint does not 
remain permanently set). 


Description 
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/TERMINATING 

Causes the debugger to break when a process does an image exit. The debugger 
always gains control and displays its prompt when the last image of a one-process 
or multiprocess program exits. A process is terminated when the image has 
executed the $EXIT system service and all of its exit handlers have executed. Do 
not specify an address expression with /TERMINATING. See also /ACTIVATING. 


/VECTOR_INSTRUCTION 

Causes the debugger to break on every vector instruction encountered during 
program execution. Do not specify an address expression with /VECTOR_ 
INSTRUCTION. See also /INTO and /OVER. 


When a breakpoint is triggered, the debugger takes the following action: 
Suspends program execution at the breakpoint location. 


2. If/AFTER was specified when the breakpoint was set, checks the AFTER 
count. If the specified number of counts has not been reached, execution is 
resumed and the debugger does not perform the remaining steps. 


3. Evaluates the expression in a WHEN clause, if one was specified when 
the breakpoint was set. If the value of the expression is false, execution is 
resumed and the debugger does not perform the remaining steps. 


4. Reports that execution has reached the breakpoint location by issuing a 
"break ... " message, unless /SILENT was specified. 


5. Displays the line of source code at which execution is suspended, unless 
/NOSOURCE or /SILENT was specified when the breakpoint was set, or SET 
STEP NOSOURCE was entered previously. 


6. Executes the commands in a DO clause, if one was specified when the 
breakpoint was set. If the DO clause contains a GO command, execution 
continues and the debugger does not perform the next step. 


7. Issues the prompt. 


You set a breakpoint at a particular location in your program by specifying an 
address expression with the SET BREAK command. You set a breakpoint on 
consecutive source lines, classes of instructions, or events by specifying a qualifier 
with the SET BREAK command. Generally, you must specify either an address 
expression or a qualifier, but not both. Exceptions are the /EVENT and /RETURN 
qualifiers. 


The /LINE qualifier sets a breakpoint on each line of source code. 


The following qualifiers set breakpoints on classes of instructions. Use of 
these qualifiers and of the /LINE qualifier causes the debugger to trace every 
instruction of your program as it executes and thus significantly slows down 
execution: 


ANSTRUCTION[=(opcode[, ... ])] 
/RETURN 
/VECTOR_INSTRUCTION 
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The following qualifiers set breakpoints on classes of events: 


/ACTIVATING 
/EVENT=event-name 
/EXCEPTION 
/TERMINATING 


The following qualifiers affect what happens at a routine call: 
AINNTO 
/INO]JSB 
/OVER 
/[INOJSHARE 
AINO]SYSTEM 


The following qualifiers affect what output is displayed when a breakpoint is 
reached: 


/(NOJSILENT 
/[NO]JSOURCE 


The following qualifiers affect the timing and duration of breakpoints: 


/AFTER:n 
/TEMPORARY 


The /MODIFY qualifier is used to monitor changes at program locations (typically 
changes in the values of variables). 


If you set a breakpoint at a location currently used as a tracepoint, the tracepoint 
is canceled in favor of the breakpoint, and vice versa. 


Breakpoints can be user defined or predefined. User defined breakpoints are 
those that you set explicitly with the SET BREAK command. Predefined 
breakpoints, which depend on the type of program you are debugging (for 
example, Ada or multiprocess), are established automatically when you invoke 
the debugger. Use the SHOW BREAK command to identify all breakpoints that 
are currently set. Any predefined breakpoints are identified as such. 


User defined and predefined breakpoints are set and canceled independently. 
For example, a location or event can have both a user defined and a predefined 
breakpoint. Canceling the user defined breakpoint does not affect the predefined 
breakpoint, and conversely. 


Related commands: 


CANCEL ALL 

GO 

(SET,SHOW) EVENT_FACILITY 
SET STEP [NO]JSOURCE 

SET TRACE 

SET WATCH 

(SHOW,CANCEL) BREAK 
STEP 


Examples 
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DBG> SET BREAK SWAP\%LINE 12 


This command causes the debugger to break on line 12 of module SWAP. 


DBG> SET BREAK/AFTER:3 SUB2 


This command causes the debugger to break on the third and subsequent 
times that SUB2 (a routine) is executed. 


DBG> SET BREAK/NOSOURCE LOOP1 DO (EXAMINE D; STEP; EXAMINE Y; GO) 


This command causes the debugger to break at location LOOPI. At the 
breakpoint, the following commands are issued, in the order given: EXAMINE 
D, STEP, EXAMINE Y, and GO. The /NOSOURCE qualifier suppresses the 
display of source code at the breakpoint. 


DBG> SET BREAK ROUT3 WHEN (X > 4) DO (EXAMINE Y) 


This command causes the debugger to break on routine ROUT3 when 
X is greater than 4. At the breakpoint, the EXAMINE Y command is 
issued. The syntax of the conditional expression in the WHEN clause is 
language-dependent. 


DBG> SET BREAK/TEMPORARY 1440 
DBG> SHOW BREAK 

breakpoint at 1440 [temporary] 
DBG> 


This command sets a temporary breakpoint at memory address 1440. After 
that breakpoint is triggered, it disappears. 


DBG> SET BREAK/LINE 


This command causes the debugger to break on the beginning of every source 
line encountered during program execution. 


DBG> SET BREAK/LINE WHEN (X .NE. 0) 
DBG> SET BREAK/INSTRUCTION WHEN (X .NE. 0) 


These two commands cause the debugger to break when X is not equal to 0. 
The first command tests for the condition at the beginning of every source line 
encountered during execution. The second command tests for the condition 
at each instruction. The syntax of the conditional expression in the WHEN 
clause is language-dependent. 


DBG> SET BREAK/INSTRUCTION=ADDL3 


This command causes the debugger to break whenever the instruction ADDL3 
is about to be executed. 


DBG> SET BREAK/LINE/INTO/NOSHARE/NOSYSTEM 


This command causes the debugger to break on the beginning of every source 
line, including lines in called routines (INTO) but not in shareable image 
routines (/NOSHARE) or system routines /(NOSYSTEM). 
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10. 


11. 


12. 


13. 


14, 


DBG> SET BREAK/RETURN ROUT4 

This command causes the debugger to break whenever the RET instruction of 
routine ROUT4 is about to be executed. 
DBG> SET BREAK/RETURN %LINE 14 


This command causes the debugger to break whenever the RET instruction 
of the routine that includes line 14 is about to be executed. This form of the 
command is useful if execution is currently suspended within a routine and 
you want to set a breakpoint on that routine’s RET instruction. 


DBG> SET BREAK/EXCEPTION DO (SET MODULE/CALLS; SHOW CALLS) 


This command causes the debugger to break whenever an exception is 
signaled. At the breakpoint, the SET MODULE/CALLS and SHOW CALLS 
commands are issued. 


DBG> SET BREAK/EVENT=RUN RESERVE, %TASK 3 


This command sets two breakpoints, which are associated with task 
RESERVE and task 3 (task ID = 3), respectively. Each breakpoint is triggered 
whenever its associated task makes a transition to the RUN state. 


DBG _1> SET BREAK/ACTIVATING 


This command causes the debugger to break whenever a process of a 
multiprocess program is brought under debugger control. 


SET DEFINE 


Format 


Parameters 


Description 


Example 
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Establishes a default qualifier (ADDRESS, /COMMAND, /PROCESS_GROUFP, or 
/VALUE) for the DEFINE command. 


SET DEFINE define-default 


define-default 
Specifies the default to be established for the DEFINE command. Valid keywords 
(which correspond to DEFINE command qualifiers) are as follows: 


ADDRESS Subsequent DEFINE commands are treated as 
DEFINE/ADDRESS. This is the default. 

COMMAND Subsequent DEFINE commands are treated as 
DEFINE/COMMAND. 


PROCESS_GROUP Subsequent DEFINE commands are treated as 
DEFINE/PROCESS_GROUP. 


VALUE Subsequent DEFINE commands are treated as 
DEFINE/VALUE. 


The SET DEFINE command establishes a default qualifier for subsequent 

DEFINE commands. The parameters that you specify in the SET DEFINE 
command have the same names as the DEFINE command qualifiers. The 

qualifiers determine whether the DEFINE command binds a symbol to an 

address, a command string, a list of processes, or a value. 


You can override the current DEFINE default for the duration of a single 
DEFINE command by specifying another qualifier. Use the SHOW DEFINE 
command to identify the current DEFINE defaults. 


Related commands: 


DEFINE 
DEFINE/PROCESS_GROUP 
DELETE 

SHOW DEFINE 

SHOW SYMBOL/DEFINED 


DBG> SET DEFINE VALUE 


The SET DEFINE VALUE command specifies that subsequent DEFINE 
commands are treated as DEFINE/VALUE. 
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Format 


Parameters 


Qualifiers 
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Establishes the editor that is invoked by the EDIT command. 


SET EDITOR [command-line] 


command-line 
Specifies a command line to invoke a particular editor on your system when you 
use the EDIT command. 


You must specify a command line unless you use the /CALLABLE_EDT, 
/CALLABLE_LSEDIT, or /CALLABLE_TPU qualifiers. If you do not use one 
of these qualifiers, the editor specified in the SET EDITOR command line is 
spawned to a subprocess when you enter the EDIT command. 


You can specify a command line with the /CALLABLE_LSEDIT and /CALLABLE_ 
TPU qualifiers, but not with the /CALLABLE_EDT qualifier. 


/CALLABLE_EDT 

Specifies that the callable version of the EDT editor is invoked when you use 
the EDIT command. Do not specify a command line with /CALLABLE_EDT (a 
command line of "EDT" is used). 


/CALLABLE_LSEDIT 

Specifies that the callable version of the VAX Language-Sensitive Editor 
(LSEDIT) is invoked when you use the EDIT command. If you also specify a 
command line, it is passed to callable LSEDIT. If you do not specify a command 
line, the default command line is "LSEDIT". 


/CALLABLE_TPU 

Specifies that the callable version of the VAX Text Processing Utility (VAXTPU) is 
invoked when you use the EDIT command. If you also specify a command line, it 
is passed to callable VAXTPU. If you do not specify a command line, the default 
command line is "TPU". 


/START_POSITION 

/NOSTART_POSITION (default) 

Currently, only VAXTPU and the VAX Language-Sensitive Editor (specified either 
as TPU or /CALLABLE_TPU, and LSEDIT or /CALLABLE_LSEDIT, respectively) 
support /START_POSITION. 


Controls whether the /START_POSITION qualifier is appended to the specified 
or default command line when the EDIT command is used. This qualifier affects 
the initial position of the editor’s cursor. By default, ((/NOSTART_POSITION), the 
editor’s cursor is placed at the beginning of source line 1, regardless of which line 
is centered in the debugger’s source display or whether a line number is specified 
in the EDIT command. If /START_POSITION is specified, the cursor is placed 
either on the line whose number is specified in the EDIT command, or (if no line 
number is specified) on the line that is centered in the current source display. 


Description 


Examples 
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The SET EDITOR command enables you to specify any editor that is installed 
on your system. In general, the command line specified as parameter to the SET 
EDITOR command is spawned and executed in a subprocess. However, if you 
use EDT, LSEDIT, or VAXTPU, you have the option of invoking these editors 

in a more efficient way. You can specify the /CALLABLE_EDT, /CALLABLE_ 
LSEDIT, or /CALLABLE_TPU qualifiers, which cause the callable versions of 
EDT, LSEDIT, and VAXTPU, respectively, to be invoked by the EDIT command. 
In the case of LSEDIT and VAXTPU, you can also specify a command line that is 
executed by the callable editor. 


Related commands: 


EDIT 
(SET,SHOW,CANCEL) SOURCE 
SHOW DEFINE 


1. DBG> SET EDITOR ’@MAILSEDIT ""’ 
This command causes the EDIT command to spawn the command line 
*@MAIL$EDIT ""’, which invokes the same editor as you use in MAIL. 

2. DBG> SET EDITOR/ CALLABLE TPU 
This command causes the EDIT command to invoke callable VAXTPU with 
the default command line of TPU. 

8. DBG> SET EDITOR/CALLABLE_TPU TPU/SECTION=MYSECINI. TPUSSECTION 
This command causes the EDIT command to invoke callable VAXTPU with 
the command line TPU/SECTION=MYSECINI.TPU$SECTION. 

4. DBG> SET EDITOR/CALLABLE LSEDIT/START POSITION 


This command causes the EDIT command to invoke callable LSEDIT with 
the default command line of LSEDIT. Also the /START_POSITION qualifier 
is appended to the command line, so that the editing session starts on the 
source line that is centered in the debugger’s current source display. 
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SET EVENT_FACILITY 


Format 


Parameters 


Description 
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Establishes the current event facility. 


Event facilities are available for programs that call Ada or SCAN routines or that 
use DECthreads services. 


SET EVENT_FACILITY _ facility-name 


facility-name 
Specifies an event facility. Valid facility-name keywords are as follows: 


ADA If the event facility is set to ADA, the (SET,CANCEL) BREAK and 
(SET,CANCEL) TRACE commands recognize Ada-specific events as 
well as generic, low-level task events. (Ada events consist of task 
and exception events.) 

You can set the event facility to ADA only if the main program is 
written in Ada or if the program calls an Ada routine. 


THREADS If the event facility is set to THREADS, the (SET,CANCEL) BREAK 
and (SET,CANCEL) TRACE commands recognize DECthreads- 
specific as well as generic, low-level task events. All DECthreads 
events are task (thread) events. 

You can set the event facility to THREADS only if the shareable 
image CMA$RTL is currently part of the program’s process (if that 
image is listed in a SHOW IMAGE display). 


SCAN If the event facility is set to SCAN, the (SET,;CANCEL) BREAK 
and (SET,CANCEL) TRACE commands recognize SCAN (pattern- 
matching) events. 
You can set the event facility to SCAN only if the main program is 
written in SCAN or if the program calls a SCAN routine. 


The current event facility (ADA, THREADS, or SCAN) defines the eventpoints 
that you can set with the SET BREAK/EVENT and SET TRACE/EVENT 
commands. 


When invoked with a program that is linked with an event facility, the debugger 
automatically sets the facility in a manner appropriate for the type of program. 
For example, if the main program is written in Ada or SCAN, the event facility is 
set to ADA or SCAN, respectively. 


The SET EVENT_FACILITY command enables you to change the event facility 
and thereby change your debugging context. This is useful if you have a 
multilanguage program and want to debug a routine that is associated with 
an event facility but that facility is not currently set. 


Example 
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Note 


Currently you cannot use both Ada and DECthreads tasking services in 
the same program. This implies that you can change the event facility 
only from ADA to SCAN or from DECthreads to SCAN, or conversely. 


Use the SHOW EVENT_FACILITY command to identify the event names 
associated with the current event facility. These are the keywords that you can 
specify with the (SET,CANCEL) BREAK/EVENT and (SET,CANCEL) TRACE 
/EVENT commands. 


Related commands: 


(SET,CANCEL) BREAK/EVENT 
(SET,CANCEL) TRACE/EVENT 
SHOW BREAK 

SHOW EVENT_FACILITY 
SHOW IMAGE 

SHOW TASK 

SHOW TRACE 


DBG> SET EVENT FACILITY THREADS 
This command establishes THREADS (DECthreads) as the current event facility. 
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SET IMAGE 


Format 


Parameters 


Qualifiers 


Description 
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Loads symbol information for one or more shareable images and establishes the 
current image. 


SET IMAGE [image-namef[, ... J] 


image-name 

Specifies a shareable image to be "set." Do not use the asterisk (*) wildcard 
character. Instead, use the /ALL qualifier. Do not specify an image name with 
/ALL. 


/ALL 
Specifies that all shareable images are set. Do not specify an image with /ALL. 


The SET IMAGE command builds data structures for one or more specified 
images but does not set any modules within the images specified. 


The "current" image is the current debugging context: you have access to 
symbols in the current image. If only one image is specified with the SET IMAGE 
command, that image becomes the current image. If a list of images is specified, 
the last one in the list becomes the current image. If /ALL is specified, the 
current image is unchanged. 


Before an image can be set with the SET IMAGE command, it must have been 
linked with the /DEBUG or /TRACEBACK qualifier on the LINK command. If an 
image was linked /NOTRACEBACK, no symbol information is available for that 
image and you cannot specify it with the SET IMAGE command. 


Definitions created with the DEFINE/ADDRESS and DEFINE/VALUE commands 
are available only when the image in whose context they were created is the 
current image. When you use the SET IMAGE command to establish a new 
current image, these definitions are temporarily unavailable. Definitions created 
with the DEFINE/COMMAND and DEFINE/KEY commands are always available 
for all images, however. 


Related commands: 


SET MODE [NOJDYNAMIC 
(SET,SHOW,CANCEL) MODULE 
(SHOW,CANCEL) IMAGE 
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Example 


DBG> SET IMAGE SHARE1 
DBG> SET MODULE SUBR 
DBG> SET BREAK SUBR 


This sequence of commands shows how to set a breakpoint on routine SUBR in 
module SUBR of shareable image SHARE1. The SET IMAGE command sets 
the debugging context to SHARE1. The SET MODULE command loads the 
symbol records of module SUBR into the RST. The SET BREAK command sets a 
breakpoint on routine SUBR. 
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SET KEY 


Format 


Qualifiers 


Description 


Example 
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Establishes the current key state. 


SET KEY 


/LOG (default) 

/INOLOG 

Controls whether a message is displayed indicating that the key state has been 
set. The /LOG qualifier displays the message. 


/STATE[=state-name] 

/NOSTATE (default) 

Specifies a key state to be established as the current state. You can specify a 
predefined key state, such as GOLD, or a user-defined state. A state name can be 
any appropriate alphanumeric string. The /NOSTATE qualifier leaves ia current 
state unchanged. 


Keypad mode must be enabled (SET MODE KEYPAD) before ue can use this 
command. Keypad mode is enabled by default. 


By default, the current key state is the "DEFAULT" state. When you define 
function keys using the DEFINE/KEY command, you can use the [F_STATE 
qualifier of that command to assign a specific state name to the key definition. 
If that state is not set when you press the key, the definition is not processed. 
The SET KEY/STATE command enables you to change the current state to the 
appropriate state. 


You can also change the current state by pressing a key that causes a state 
change (a key that was defined with the DEFINE/KEY/LOCK_STATE/SET_ 
STATE qualifier combination). 


Related commands: 


DELETE/KEY 
DEFINE/KEY 
SHOW KEY 


DBG> SET KEY/STATE=PROG3 


This command changes the key state to the PROGS state. The user can now use 
the key definitions that are associated with this state. 
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Format 


Parameters 


Description 


Establishes the current language. 


SET LANGUAGE _language-name 


language-name 
Specifies a language. Valid keywords are ADA, BASIC, BLISS, C, COBOL, 
DIBOL, FORTRAN, MACRO, PASCAL, PLI, RPG, SCAN, and UNKNOWN. 


When you invoke the debugger with the RUN command, the debugger sets the 
current language to that in which the module containing the main program is 
written. This is usually the module containing the image transfer address. To 
debug a module written in a different source language from that of the main 
program, you can change the language with the SET LANGUAGE command. 


The current language setting determines how the debugger parses and interprets 
the names, operators, and expressions you specify in debugger commands, 
including things like the typing of variables, array and record syntax, the default 
radix for the entry and display of integer data, case sensitivity, and so on. The 
language setting also determines how the debugger formats and displays data 
associated with your program. 


The default radix for both data entry and display is decimal for all languages 
except BLISS and MACRO. It is hexadecimal for BLISS and MACRO. The default 
type for program locations that do not have a compiler generated type is longword 
integer. 


The SET LANGUAGE UNKNOWN command is used when debugging a program 
that is written in an unsupported language. To maximize the usability of the 
debugger with unsupported languages, the SET LANGUAGE UNKNOWN 
command causes the debugger to accept a large set of data formats and operators, 
including some that might be specific to only a few supported languages. 


The operators and constructs that are recognized for each SET LANGUAGE 
command parameter are identified in Appendix E. 


Related commands: 


EVALUATE 
EXAMINE 
DEPOSIT 

SET MODE 

SET RADIX 

SET TYPE 

SHOW LANGUAGE 
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Examples 


1. DBG> SET LANGUAGE COBOL 
This command establishes COBOL as the current language. 


2. DBG> SET LANGUAGE PASCAL 


This command establishes Pascal as the current language. 


CD-142 


SET LOG 


Format 


Parameters 


Description 


Examples 
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Specifies a log file to which the debugger writes after a SET OUTPUT LOG 
command has been entered. 


SET LOG _file-spec 


file-spec 

Denotes the file specification of the log file. If you do not supply a full file 
specification, the debugger assumes SYS$DISK:[ ]JDEBUG.LOG as the default file 
specification for any missing field. 


If you specify a version number and that version of the file already exists, the 
debugger writes to the file specified, appending the log of the debugging session 
onto the end of that file. 


The SET LOG command only determines the name of a log file; it does not cause 
the debugger to create or write to the specified file. The SET OUTPUT LOG 
command accomplishes that. | 


If you have entered a SET OUTPUT LOG command but no SET LOG command, 
the debugger writes to the file SYS$DISK:[ JDEBUG.LOG by default. 


If the debugger is writing to a log file and you specify another log file with the 
SET LOG command, the debugger closes the former file and begins writing to the 
file specified in the SET LOG command. 


Related commands: 


SET OUTPUT LOG 
SET OUTPUT SCREEN_LOG 
SHOW LOG 


1. DBG> SET LOG CALC 
DBG> SET OUTPUT LOG 


In this example, the SET LOG command specifies the debugger log file to 
be SYS$DISK:[ JCALC.LOG. The SET OUTPUT LOG command causes user 
input and debugger output to be logged to that file. 


2. DBG> SET LOG "[CODEPROJ]FEB29.TMP" 
DBG> SET OUTPUT LOG 


In this example, the SET LOG command specifies the debugger log file to 
be [CODEPROJ]JFEB29.TMP. The SET OUTPUT LOG command causes user 
input and debugger output to be logged to that file. 
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SET MARGINS 


Format 


Parameters 


Description 
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Specifies the leftmost and rightmost source-line character position at which to 
begin and end display of a source line. 


SET MARGINS) rm 
Im:rm 
Im: 
rm 


Im 
The source-line character position at which to begin display of the line of source 
code (the left margin). 


rm 
The source-line character position at which to end display of the line of source 
code (the right margin). 


The SET MARGINS command affects only the display of source lines. It does not 
affect the display of other debugger output, as from an EXAMINE command. 


The SET MARGINS command is useful for controlling the display of source code 
when, for example, the code is deeply indented or long lines wrap at the right 
margin. In such cases, you can set the left margin to eliminate indented space in 
the source display, and you can decrease the right margin setting (from its default 
value of 255) to truncate lines and prevent them from wrapping. 


The SET MARGINS command is useful mostly in line (noscreen) mode. In line 
mode, the SET MARGINS command affects the display of source lines resulting 
from a TYPE, EXAMINE/SOURCE, SEARCH, or STEP command, or when a 
breakpoint, tracepoint, or watchpoint is triggered. 


In screen mode, the SET MARGINS command has no effect on the display of 
source lines in a source display, such as the predefined display SRC. Therefore it 
does not affect the output of a TYPE or EXAMINE/SOURCE command, since that 
output is directed at a source display. The SET MARGINS command affects only 
the display of any source code that might appear in-an output or DO display (for 
example after a STEP command has been executed). However, such source-code 
display is normally suppressed if you invoke screen mode with the keypad key 
sequence PF1-PF3, because that sequence issues the SET STEP NOSOURCE 
command in addition to SET MODE SCREEN, to eliminate redundant source 
display. 


By default, the debugger displays a source line beginning at character position 1 
of the source line. This is actually character position 9 on your terminal screen. 
The first eight character positions on the screen are reserved for the line number 
and cannot be manipulated by the SET MARGINS command. 


If you specify a single number, the debugger sets the left margin to 1 and the 
right margin to the number specified. 


Examples 
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If you specify two numbers, separated with a colon, the debugger sets the left 
margin to the number on the left of the colon and the right margin to the number 
on the right. 


If you specify a single number followed by a colon, the debugger sets the left 
margin to that number and leaves the right margin unchanged. 


If you specify a colon followed by a single number, the debugger sets the right 
margin to that number and leaves the left margin unchanged. 


Related commands: 


SET STEP [NO]JSOURCE 
SHOW MARGINS 


1. DBG> SHOW MARGINS 
left margin: 1, right margin: 255 
DBG> TYPE 14 
module FORARRAY 
143 DIMENSION IARRAY (4:5,5), VECTOR(10), 13D(3,3,4) 
DBG> 


This example displays the default margin settings for a line of source code (1 
and 255). 


2. DBG> SET MARGINS 39 
DBG> SHOW MARGINS 
left margin: 1, right margin: 39 
DBG> TYPE 14 
module FORARRAY 
14: DIMENSION IARRAY(4:5,5), VECTOR 
DBG> 


This example shows how the display of a line of source code changes when 
you change the right margin setting from 255 to 39. 


3. DBG> SET MARGINS 10:45 
DBG> SHOW MARGINS 
left margin: 10 , right margin: 45 
DBG> TYPE 14 
module FORARRAY 
14: IMENSION IARRAY(4:5,5), VECTOR(10), 
DBG> 


This example shows the display of the same line of source code after both 
margins are changed. 


4, DBG> SET MARGINS :100 
DBG> SHOW MARGINS 
left margin: 10 , right margin: 100 
DBG> 


This example shows how to change the right margin setting while retaining 
the previous left margin setting. ; 
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SET MARGINS 


5. DBG> SET MARGINS 5: 
DBG> SHOW MARGINS 


left margin: 5 , right margin: 100 
DBG> 


This example shows how to change the left margin setting while retaining the 
previous right margin setting. 
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SET MAX_SOURCE_FILES 


Format 


Parameters 


Description 


Example 


Specifies the maximum number of source files that the debugger can keep open at 
any one time. 


SET MAX_SOURCE_FILES integer 


integer 

A decimal integer specifying the maximum number of source files that the 
debugger can keep open at any one time. The value cannot exceed 20. The 
default is 5. 


By default, the debugger can keep five source files open at any one time. 


Opening a source file requires the use of an I/O channel, which is a limited 
system resource. Both the program and the debugger use I/O channels. To 
ensure that the debugger does not use all available I/O channels and thus cause 
the program to fail (for lack of an available I/O channel), you can enter the SET 
MAX SOURCE_FILES command to specify the maximum number of source files 
(and thus source file I/O channels) that the debugger can use at any one time. 


The value of MAX_SOURCE_FILES does not limit the number of source files that 
the debugger can open; rather, it limits the number that can be kept open at any 

one time. Thus, if the debugger reaches this limit, it must close a file in order to 

open another one. 


Note also that setting MAX _SOURCE_FILES to a very small number can make 
the debugger’s use of source files inefficient. 


Related commands: 


(SET,SHOW,CANCEL) SOURCE 
SHOW MAX_SOURCE_FILES 


DBG> SHOW MAX_SOURCE_FILES 
max source files: 5 

DBG> SET MAX SOURCE FILES 8 
DBG> SHOW MAX_SOURCE_FILES 
max source files: 8 

DBG> 


In this example, the SET MAX _SOURCE_FILES 8 command enables the 
debugger to keep a maximum of eight files open at any one time. 
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SET MODE 


Enables or disables a debugger mode. 


Format 
SET MODE mode[,... ] 


Parameters 
mode 


Specifies a debugger mode to be enabled or disabled. Valid keywords are as 


follows: 
DYNAMIC 


NODYNAMIC 


G_FLOAT 


NOG_FLOAT 


CD-148 


Enables dynamic mode. When dynamic mode is 
enabled, the debugger sets modules and images 
automatically during program execution so that you 
typically do not have to enter the SET MODULE 

or SET IMAGE command. Specifically, whenever 
the debugger interrupts execution (whenever 

the debugger prompt is displayed), the debugger 
automatically sets the module and image that 
contain the routine in which execution is currently 
suspended. If the module or image is already set, 
dynamic mode has no effect on that module or image. 
The debugger issues an informational message when 
its sets a module or image automatically. SET MODE 
DYNAMIC is the default. . 


Disables dynamic mode. Because additional memory 
is allocated when a module or image is set, you 
might want to disable dynamic mode if performance 
becomes a problem (you can also free up memory by 
canceling modules and images with the CANCEL 
MODULE and CANCEL IMAGE commands). When 
dynamic mode is disabled, you must set modules and 
images explicitly with the SET MODULE and SET 
IMAGE commands. 


Specifies that the debugger interpret double-precision 
floating-point constants entered in expressions as G_ 

FLOAT (does not affect the interpretation of variables 
declared in your program). 


Specifies that the debugger interpret double-precision 
floating-point constants entered in expressions as D_ 

FLOAT (does not affect the interpretation of variables 
declared in your program). SET MODE NOG_FLOAT > 
is the default. 


INTERRUPT 


NOINTERRUPT 


KEYPAD 


NOKEYPAD 


LINE 


NOLINE 
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(Applies to a multiprocess debugging configuration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS.) Specifies that, when program 
execution is suspended in any process, the debugger 
interrupts execution in any other processes that were 
executing images and prompts for input. SET MODE 
INTERRUPT is the default. 


(Applies to a multiprocess debugging configuration— 
that is, when DBG$PROCESS has the value 
MULTIPROCESS.) Specifies that, when program 
execution is suspended in any process, the debugger 
take the following action: 


e If execution was suspended because of an 
unhandled exception, the debugger interrupts 
execution in any other processes that were 
executing images and prompts for input. 


e If execution was suspended because of a 
breakpoint or watchpoint or the completion of 
a STEP command, the debugger lets execution 
proceed in any other processes that were 
executing images and does not display the prompt 
unless execution is eventually suspended in all 
these processes. As long as execution continues 
in any process, the debugger does not prompt for 
input. In such cases, use Ctrl/C to interrupt all 
processes and display the prompt. 


Enables keypad mode. When keypad mode is 
enabled, you can use the keys on the numeric keypad 
to perform certain predefined functions. Several 
debugger commands, especially useful in screen mode, 
are bound to the keypad keys (see Appendix B). You 
can also redefine the key functions with the DEFINE 
/KEY command. SET MODE KEYPAD is the default. 


Disables keypad mode. When keypad mode is 
disabled, the keys on the numeric keypad do not 
have predefined functions, nor can you assign 
debugger functions to those keys with DEFINE/KEY 
commands. | 
Specifies that the debugger display program locations 
in terms of line numbers, if possible. SET MODE 
LINE is the default. 

Specifies that the debugger display program locations 
as routine-name + byte-offset rather than in terms of 
line numbers. 
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OPERANDS [=keyword] 


NOOPERANDS 


SCREEN 


NOSCREEN 


SCROLL 


NOSCROLL 


SEPARATE 


-~ NOSEPARATE 
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Specifies that the EXAMINE command, when used 
to examine an instruction, display the address and 
contents of the instruction’s operands in addition 

to the instruction and its operands. The level of 
information displayed about any nonregister operands 
depends on whether you use the keyword BRIEF or 
FULL. The default is OPERANDS=BRIEF. 


Specifies that the EXAMINE command, when used to 
examine an instruction, display only the instruction 
and its operands. SET MODE NOOPERANDS is the 
default. 


Enables screen mode. When screen mode is enabled, 
you can divide the terminal screen into rectangular 
regions, so different data can be displayed in different 
regions. Screen mode enables you to view more 
information more conveniently than the default, line- 
oriented, noscreen mode. You can use the predefined 
displays, or you can define your own. 


Disables screen mode. SET MODE NOSCREEN is 
the default. 


Enables scroll mode. When scroll mode is enabled, 
a screen-mode output or DO display is updated by 
scrolling the output line by line, as it is generated. 
SET MODE SCROLL is the default. 


Disables scroll mode. When scroll mode is disabled, 
a screen-mode output or DO display is updated only 
once per command, instead of line by line as it is 
generated. Disabling scroll mode reduces the amount 
of screen updating that takes place and can be useful 
with slow terminals. 


(Applies only to workstations running VWS.) Specifies 
that a separate window be created for debugger input 
and output. This feature is useful when debugging 
screen-oriented programs, because it moves all 
debugger displays out of the window that contains the 
program’s input and output. The separate window is 
created with a height of 24 lines and a width of 80 
columns wide, emulating a VT-series terminal screen. 


(Applies only to workstations running VWS.) Specifies 
that no separate window be created for debugger 
input and output. SET MODE NOSEPARATE is the 
default. 


Description 


Example 


Debugger Command Dictionary 
SET MODE 


SYMBOLIC Enables symbolic mode. When symbolic mode is 


enabled, the debugger displays the locations denoted 
by address expressions symbolically (if possible) 
and displays instruction operands symbolically (if 
possible). EXAMINE/NOSYMBOLIC can be used to 
override SET MODE SYMBOLIC for the duration of 
an EXAMINE command. SET MODE SYMBOLIC is 
the default. | 


NOSYMBOLIC Disables symbolic mode. When symbolic mode is 


disabled, the debugger does not attempt to symbolize 
numeric addresses (it does not cause the debugger 
to convert numbers to names). This is useful if 

you are interested in identifying numeric addresses 
rather than their symbolic names (if symbolic names 
exist for those addresses). When symbolic mode 

is disabled, command processing might speed up 
somewhat, because the debugger does not need to 
convert numbers to names. EXAMINE/SYMBOLIC 
can be used to override SET MODE NOSYMBOLIC 
for the duration of an EXAMINE command. 


See the parameter descriptions for details about the SET MODE command. The 
default values of these modes are the same for all languages. 


Related commands: 


EVALUATE 

EXAMINE 

DEFINE/KEY 

DEPOSIT 

DISPLAY 
(SET,SSHOW,CANCEL) IMAGE 
(SET,SHOW,CANCEL) MODULE 
SET PROMPT 
(SET,SSHOW,CANCEL) RADIX 
(SET,SHOW) TYPE 
(SHOW,CANCEL) MODE 
SYMBOLIZE 


DBG> SET MODE SCREEN 


This command puts the debugger in screen mode. 


CD-151 


Debugger Command Dictionary 
SET MODULE 


SET MODULE 


Format 


Parameters 


Qualifiers 


Description 
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Loads the symbol records of a module in the current image into the run-time 
symbol table (RST) of that image. 


SET MODULE [module-namef[, ... ]] 


module-name 

Specifies a module of the current image whose symbol records are loaded into 
the RST. Do not use the asterisk (*) wildcard character. Instead, use the /ALL 
qualifier. Do not specify a module name with /ALL. 


/ALL 
Specifies that the symbol records of all modules in the current image be loaded 
into the RST. Do not specify a module name with /ALL. 


/CALLS . 
Sets all the modules that currently have routines on the call stack. If a module is 
already set, /CALLS has no effect on that module. Do not specify a module name 
with /CALLS. 


/RELATED (default) 
/NORELATED . 
Applies to Ada programs. 


Controls whether the debugger loads into the RST the symbol records of a 
module that is related to a specified module through a with-clause or subunit 
relationship. 


SET MODULE/RELATED loads symbol records for related modules as well as 
for those specified. This makes names declared in related modules visible so that 
you can reference them in debugger commands exactly as they can be referenced 
within the Ada source code. SET MODULE/NORELATED loads symbol records 
only for modules that are specified (no symbol records are loaded for related 
modules). 


Note 


The current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 


Symbol records must be present in the run-time symbol table (RST) if the . 
debugger is to recognize and properly interpret the symbols declared in your 
program. The process by which the symbol records of a module are loaded into 
the RST is called setting a module. 


Examples 
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At debugger startup, the debugger sets the module containing the transfer 
address (the main program). By default, dynamic mode is enabled (SET MODE 
DYNAMIC). Therefore, the debugger sets modules (and images) automatically 
as the program executes so that you can reference symbols as you need them. 
Specifically, whenever execution is suspended, the debugger sets the module and 
image containing the routine in which execution is suspended. In the case of 
Ada programs, as a module is set dynamically, its related modules are also set 
automatically, by default, to make the appropriate symbols accessible (visible). 


Dynamic mode makes accessible most of the symbols you might need to reference. 
If you need to reference a symbol in a module that is not already set, proceed as 
follows: 


¢ Ifthe module is in the current image, use the SET MODULE command to set 
the module where the symbol is defined. 


¢ Ifthe module is in another image, use the SET IMAGE command to make 
that image the current image, then use the SET MODULE command to set 
the module where the symbol is defined. 


If dynamic mode is disabled (SET MODE NODYNAMIOC), only the module 
containing the transfer address is set automatically. You must set any other 
modules explicitly. 


If you use the SET IMAGE command to establish a new current image, all 
modules previously set remain set. However, only the symbols in the set modules 
of the current image are accessible. Symbols in the set modules of other images 
are temporarily unaccessible. 


When dynamic mode is enabled, memory is allocated automatically to 
accommodate the increasing size of the RST. If dynamic mode is disabled, the 
debugger automatically allocates more memory as needed when you set a module 
or an image. Whether dynamic mode is enabled or disabled, if performance 
becomes a problem as more modules are set, use the CANCEL MODULE 
command to reduce the number of set modules. 


If a parameter in a SET SCOPE command designates a program location in a 
module that is not already set, the SET SCOPE command sets that module. 


See Section E.1.14 for information specific to Ada programs. 
Related commands: 


(SET,SHOW,CANCEL) IMAGE 
SET MODE [NO]DYNAMIC 
(SHOW,CANCEL) MODULE 


1. DBG> SET MODULE SUB1 


This command sets module SUB1 (loads the symbol records of module SUB1 
into the RST). — 
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DBG> SET IMAGE SHARE3 
DBG> SET MODULE MATH 
DBG> SET BREAK %LINE 31 


In this example, the SET IMAGE command makes shareable image SHARE3 
the current image. The SET MODULE command sets module MATH in 
image SHARE3. The SET BREAK command sets a breakpoint on line 31 of 
module MATH. 


DBG> SHOW MODULE/SHARE 

module name symbols language size 
FOO yes MACRO 432 
MAIN no FORTRAN 280 
SHARESDEBUG no Image 0 
SHARES LIBRTL no Image 0 
SHARESMTHRTL no Image 0 
SHARESSHARE1 no Image 0 
SHARES SHARE2 no Image 0 
total modules: 17. bytes allocated: 162280. 


DBG> SET MODULE SHARESSHARE2 
DBG> SHOW SYMBOL * IN SHARESSHARE2 


In this example, the SHOW MODULE/SHARE command identifies all 
modules in the current image and all shareable images (the names 

of the shareable images are prefixed with "SHARE$"). The SET 
MODULE SHARE$SHARE2 command sets the shareable image module 
SHARE$SHARE2. The SHOW SYMBOL command identifies any universal 
symbols defined in the shareable image SHAREZ2. See the description of the 
/SHARE qualifier of the SHOW MODULE command for more information. 
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SET OUTPUT 


Format 


Parameters 


Description 


Enables or disables a debugger output option. 


SET OUTPUT output-option[, ... ] 


output-option 
Specifies an output option to be enabled or disabled. Valid keywords are as 
follows: . 


LOG Specifies that debugger input and output be recorded 
in a log file. If you specify the log file by the SET LOG 
command, the debugger writes to that file; otherwise, by 
default the debugger writes to SYS$DISK[ ]:DEBUG.LOG. 


NOLOG Specifies that debugger input and output not be recorded in 
a log file. NOLOG is the default. 
SCREEN_LOG Specifies that, while in screen mode, the screen contents be 


recorded in a log file as the screen is updated. To log the 
screen contents you must also specify SET OUTPUT LOG. 
See the description of the LOG option regarding specifying 
the log file. 


NOSCREEN_LOG Specifies that the screen contents, while in screen mode, not 
be recorded in a log file. NOSCREEN_LOG is the default. 


TERMINAL Specifies that debugger output be displayed at the terminal. 
TERMINAL is the default. 

NOTERMINAL Specifies that debugger output, except for diagnostic 
messages, not be displayed at the terminal. 

VERIFY Specifies that the debugger echo, on the current output 


device, each input command string that it is executing from 
a command procedure or DO clause. The current output 
device is by default SYS$OUTPUT, the terminal, but can be 
redefined with the logical name DBG$OUTPUT. 


NOVERIFY Specifies that the debugger not display each input command 
string that it is executing from a command procedure or DO 
clause. NOVERIFY is the default. 


Debugger output options control the way in which debugger responses to 
commands are displayed and recorded. See the parameter descriptions for 
details about the SET OUTPUT command. 


Related commands: 


@ (Execute Proced“re) 
(SET,SHOW) ATS”.GN. 
(SET,SSHOW) LOG 

SET MODE SCREEN 
SHOW OUTPUT 
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DBG> SET OUTPUT VERIFY, LOG, NOTERMINAL 


This command specifies that the debugger take the following action: 


Output each command string that it is executing from a command procedure 
or DO clause (VERIFY) 


Record debugger output and user input in a log file (LOG) 


Not display output at the terminal, except for diagnostic messages 
(NOTERMINAL) 


SET PROCESS 


Format 


Parameters 


Debugger Command Dictionary 
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Establishes the visible process, changes characteristics of one or more processes, 
or enables/disables dynamic process setting. 


Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 


value MULTIPROCESS). 


SET PROCESS [process-spec[, .. . ]] 


process-spec 


Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name 


[%PROCESS_NAME] "process-name" 


%PROCESS_PID process_id 
%PROCESS_NUMBER proc-number 
(or %PROC proc-number) 
process-group-name 
%NEXT_PROCESS 


%PREVIOUS_PROCESS 


%VISIBLE_PROCESS 


The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’) instead 
of quotation marks ("). 


The VMS process identification number 
(PID, a hexadecimal number). 


The number assigned to a process 
when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 


A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


The process after the visible process in 
the debugger’s circular process list. 


The process previous to the visible 
process in the debugger’s circular 
process list. 


The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. 
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Qualifiers 


Description 
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/ALL 
Applies the SET PROCESS command to all processes. Do not specify a process 
with this qualifier. Do not specify ([NOJDYNAMIC, or /VISIBLE with /ALL. 


/DYNAMIC (default) 

/NODYNAMIC 

Controls whether dynamic process setting is enabled or disabled. When dynamic 
process setting is enabled (/DYNAMIC), whenever the debugger suspends 
execution and displays its prompt, the process in which execution is suspended 
becomes the visible process automatically. When dynamic process setting is 
disabled (/NODYNAMIC), the visible process remains unchanged until you 
specify another process with the SET PROCESS/VISIBLE command. 


Do not specify a process with /[NOJDYNAMIC. Do not specify /ALL, /[NOJHOLD, 
or /VISIBLE with ([NOJDYNAMIC. 


/HOLD 

/NOHOLD 

/HOLD puts a specified process on hold. This prevents images in that process 
from executing when you enter a GO, STEP, or CALL command, unless the 
process is the visible process. A hold condition in the visible process is ignored. 


The /NOHOLD qualifier releases a specified process from a hold condition. This 
permits images in that process to execute when you enter a GO, STEP, or CALL 
command, regardless of which process is the visible process. 


The behavior described also applies when you use the DO command to broadcast 
a GO, STEP, or CALL command to specific processes. 


If no process is specified, /HOLD puts the visible process on hold, and /NOHOLD 
releases the visible process from the hold condition. 


See the descriptions of the GO, STEP, CALL, EXIT, and QUIT commands for the 
effects of these commands on processes that have or have not been put on hold. 


Do not specify /[NOJDYNAMIC with /[NOJHOLD. 


VISIBLE 

Makes the specified process the visible process. This switches your debugging 
context to the specified process, so that symbol lookups and the setting of 
breakpoints, and so on, are done in the context of that process. You must specify 
one, and only one, process. 


If you do not specify /VISIBLE, it is assumed by default. 
Do not specify /ALL, or /[NOJDYNAMIC with /VISIBLE. 


The SET PROCESS command establishes the visible process or changes 
characteristics of one or more processes. 


By default, commands are executed in the context of the visible process. The 
visible process is the process that is your current debugging context. Symbol 
lookups and the setting of breakpoints, and so on, are done in the context of the 
visible process. 


Examples 
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The DO command enables you to execute commands in the context of specific 
processes or of all processes. The DO command is equivalent to entering a SET 
PROCESS/VISIBLE command for each process specified (or for all processes, if 
no process is specified with the DO command) and then entering the specified 
commands. 


Dynamic process setting is enabled by default and is controlled with the 
/LNOJDYNAMIC qualifier. When dynamic process setting is enabled, whenever 
the debugger suspends program execution and displays its prompt, the process in 
which execution is suspended becomes the visible process automatically. 


Related commands: 


CALL 

DO 

EXIT 

GO 

QUIT 

SHOW PROCESS 
STEP 


1, DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 

* 1 TEST X YES step PROG\SLINE 50 
2 TEST Y YES break PROG\SLINE 71 

DBG_1> 


The SET PROCESS/HOLD/ALL command puts all processes on hold. This is 
confirmed in the SHOW PROCESS/ALL display. 


2. DBG_1> SET PROCESS/NOHOLD %VISIBLE | PROCESS 
DBG_ 1> SHOW PROCESS/ALL 


Number Name Hold State Current PC 
x 1 TEST X step PROG\SLINE 50 
2 TEST Y YES break PROG\%LINE 71 
DBG 1> 


The SET PROCESS/NOHOLD %VISIBLE_PROCESS command releases 
the visible process from the hold condition. This is confirmed in the SHOW 
PROCESS/ALL display. 


3. DBG_1> SET PROCESS TEST Y 
DBG 2> SHOW PROCESS 
Number Name Hold State Current PC 
* 2 TEST Y YES break PROG\%LINE 71 
DBG_2> 


The SET PROCESS TEST_Y command makes process TEST_Y the visible 
process. The SHOW PROCESS command displays information about the 
visible process by default. 
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DBG_1> SET PROCESS/HOLD/ALL 
DBG_1> DO (EXAMINE X; STEP) 
For PROCESS NUMBER 1 
MAIN PROG\X: 78 
For %PROCESS NUMBER 2 
TEST\X: 29 
stepped to MAIN PROG\$LINE 26 in %PROCESS NUMBER 1 
26: K=K+1 
DBG_1> 


The SET PROCESS/HOLD/ALL command puts all processes on hold. The DO 
command broadcasts the EXAMINE X and STEP commands to all processes 
(processes 1 and 2, in this example). The STEP command is executed in the. 
context of process 1, because a hold condition in the visible process is ignored. 
Because process 2 is on hold, execution is inhibited in that process. 
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SET PROMPT 


Format 


Parameters 


Qualifiers 


Changes the debugger prompt string to your personal preference. 


SET PROMPT _[prompt-parameter] 


prompt-parameter 

Specifies the new prompt string. If the string contains spaces, semicolons (;), or 
lowercase characters, you must enclose it in quotation marks (") or apostrophes 
('). If you do not specify a string, the current prompt string remains unchanged. 


By default, the prompt string is DBG> for a nonmultiprocess debugging 


configuration (when the logical name DBG$PROCESS is undefined or has 


the value DEFAULT). 


By default, for a multiprocess debugging configuration (when DBG$PROCESS has 
the value MULTIPROCESS), the prompt string consists of a process-independent 
prefix (specified by prompt-parameter) and a process-specific suffix (specified 

by the /[NO]SUFFIX qualifier). The suffix changes automatically as the visible 
process changes. 


/SUFFIX[=process-identifier-type] 

/NOSUFFIX 

Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


The /SUFFIX qualifier enables "dynamic prompt setting". As a result, the 
prompt string includes a process-specific suffix that automatically identifies the 
visible process. This is the default behavior. 


The /NOSUFFIX qualifier disables dynamic prompt setting. As a result, the 
prompt string does not include a process-specific suffix and does not change when 
another process becomes the visible process. 


When you invoke the debugger with the RUN command to debug a multiprocess 
program, the prompt string is DBG_1> by default. This indicates that dynamic 
prompt setting is enabled and that the visible process is process 1 (the first 
process connected to the debugger). You can control the process-specific prompt- 
string suffix by specifying one of the following process-identifier-type keywords 
with the /SUFFIX qualifier: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 
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The following table illustrates the possible kinds of prompt strings for a 
multiprocess debugging configuration. The entire prompt string depends on the 
prompt-parameter command parameter (which controls the process-independent 
prefix), and on the values of /[NO]JSUFFIX and the process-identifier-type keyword 
(which control the process-specific suffix). 


Prompt Parameter 


(Prefix) Qualifier and Keyword (Suffix) Resulting Prompt String 
none none unchanged 

none /NOSUFFIX DBG> 

none /SUFFIX DBG_process-number> } 
none /SUFFIX=PROCESS_NAME process-name> 

none /SUFFIX=PROCESS_NUMBER process-number> 
none /SUFFIX=PROCESS_PID pid> 

XYZ_ /NOSUFFIX XYZ_> 

XYZ_ /SUFFIX XYZ_process-number> 
XYZ_ /SUFFIX=PROCESS_NAME XYZ_process-name> 
XYZ_ /SUFFIX=PROCESS_NUMBER XYZ_process-number> 
XYZ_ /SUFFIX=PROCESS_PID XYZ_pid> 


lithe default prompt for a multiprocess debugging configuration is DBG_process-number>, which is 
equivalent to entering the following command: 


DBG> SET PROMPT/SUFFIX=PROCESS_NUMBER "DBG_" 


/POP 
/NOPOP (default) 
Applies only to workstations running VWS. 


The /POP qualifier causes the debugger window to pop over other windows and 
become attached to the keyboard when the debugger prompts for input. The 
/NOPOP qualifier disables this behavior (the debugger window is not popped 
over other windows and is not attached to the keyboard automatically when the 
debugger prompts for input). 


If you do not specify /POP or /NOPOP, the prompt behavior is set to /NOPOP. 


The SET PROMPT command enables you to tailor the debugger prompt string to 
your individual preference. 


If you are using a multiprocess debugging configuration (when the logical name 
DBG$PROCESS has the value MULTIPROCESS), the /[NO]JSUFFIX qualifier 
enables you to specify a process-specific prompt-string suffix. 


If you are using the debugger at a workstation, the /[NOJPOP qualifier enables 
you to control whether the debugger window is popped over other windows 
whenever the debugger prompts for input. 


Related commands: (SET,SSHOW) PROCESS. 


Examples 
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DBG> SET PROMPT "S$ " 

$ SET PROMPT "d bg: " 
db g : SET PROMPT "DBG> " 
DBG> 


The successive SET PROMPT commands change the debugger prompt from 
“DBG>” to “$”, to “db g :”, then back to “DBG>”. 


DBG_1> SET PROMPT/NOSUFFIX "dbg> " 

dbg> SET PROMPT/SUFFIX 

DBG_1> SET PROMPT/SUFFIX=PROCESS NUMBER "xyz_" 
xyz_1> SET PROMPT/SUFFIX=PROCESS NAME : 
SMITH> SET PROMPT/SUFFIX=PROCESS NAME "John " 
John SMITH> SET PROMPT/SUFFIX=PROCESS PID 
20800E4D> 


The successive SET PROMPT commands show the effect of the (/[NOJSUFFIX 
qualifier and the prompt-parameter string for multiprocess programs. 
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SET RADIX 


SET RADIX 


Format 


Parameters 


Qualifiers 


Description 
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Establishes the radix for the entry and display of integer data. When used with 
/OVERRIDE, causes all data to be displayed as integer data of the specified radix. 


SET RADIX radix 


radix 

‘Specifies the radix to be established. Valid keywords are as follows: 

BINARY Sets the radix to binary. 

DECIMAL Sets the radix to decimal. This is the default for all 
languages except BLISS and MACRO. 

DEFAULT Sets the radix to the language default. 

OCTAL Sets the radix to octal. 


HEXADECIMAL _ Sets the default radix to hexadecimal. This is the default for 
BLISS and MACRO. 


/INPUT 
Sets only the input radix (the radix for entering integer data) to the specified 
radix. 


/OUTPUT 
Sets only the output radix (the radix for displaying integer data) to the specified 
radix. 


/OVERRIDE 
Causes all data to be displayed as integer data of the specified radix. 


The current radix setting influences how the debugger interprets and displays 
integer data in the following contexts: 


¢ Integer data that you specify in address expressions or language expressions. 
¢ Integer data that is displayed by the EXAMINE and EVALUATE commands. 


The default radix for both data entry and display is decimal for all languages 
except BLISS and MACRO. It is hexadecimal for BLISS and MACRO. 


The SET RADIX command enables you to specify a new radix for data entry or 
display (the input radix and output radix, respectively). 


If you do not specify a qualifier, the SET RADIX command changes both the input 
and output radix. If you specify the INPUT or /OUTPUT qualifier, the command 
changes the input or output radix, respectively. 


If you specify the /OVERRIDE qualifier, the SET RADIX command changes only 
the output radix but causes all data (not just data that has an integer type) to be 
displayed as integer data of the specified radix. 


Examples 


Debugger Command Dictionary 
SET RADIX 


Except when used with the /OVERRIDE qualifier, the SET RADIX command 
does not affect the interpretation or display of noninteger values (such as real or 
enumeration type values). 


The EVALUATE, EXAMINE, and DEPOSIT commands have radix qualifiers 
(/BINARY, /HEXADECIMAL, and so on) that enable you to override, for the 
duration of that command, any radix previously established with the SET RADIX 
or SET RADIX/OVERRIDE command. 


You can also use the built-in symbols BIN, “DEC, %HEX, and %OCT in 
address expressions and language expressions to specify that an integer literal 
that follows should be interpreted in binary, decimal, hexadecimal, or octal radix, 
respectively (see Appendix D). 


Related commands: 


DEPOSIT 

EVALUATE 

EXAMINE | 
(SET,SHOW,CANCEL) MODE 
(SHOW,CANCEL) RADIX 


1. DBG> SET RADIX HEX 


This command sets the radix to hexadecimal. This means that, by default, 
integer data is interpreted and displayed in hexadecimal radix. 


2. DBG> SET RADIX/INPUT OCT 


This command sets the radix for input to octal. This means that, by default, 
integer data that is entered is interpreted in octal radix. 


3. DBG> SET RADIX/OUTPUT BIN 


This command sets the radix for output to binary. This means that, by 
default, integer data is displayed in binary radix. 


4, DBG> SET RADIX/OVERRIDE DECIMAL 


This command sets the override radix to decimal. This means that, by 
default, all data (not just data that has an integer type) is displayed as 
decimal integer data. 
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SET SCOPE 


Establishes how the debugger looks up symbols (variable names, routine names, 
line numbers, and so on) when a pathname prefix is not specified. 


Format 
SET SCOPE location[, ... ] 
Parameters 

location 

Denotes a program region (scope) to be used for the interpretation of symbols that 

you specify without a pathname prefix. A location can be any of the following, 

unless you specify /CURRENT or /MODULE (see the qualifier descriptions): 

pathname prefix Specifies the scope denoted by the pathname prefix. A 
pathname prefix consists of the names of one or more 
nesting program elements (module, routine, block, 
and so on), with each name separated by a backslash 
character (\ ). When a pathname prefix consists of more 
than one name, list a nesting element to the left of the 
\ and a nested element to the right of the \. A common 
pathname prefix format is module\ routine \ block\. 

If you specify only a module name and that name is 
the same as the name of a routine, use the (MODULE 
qualifier; otherwise, the debugger assumes that you are 
specifying the routine. 

n _ Specifies the scope denoted by the routine which is n 
levels down the call stack (n is a decimal integer). A 
scope specified by an integer changes dynamically as the 
program executes. The value 0 denotes the routine that 
is currently executing, the value 1 denotes the caller of 
that routine, and so on down the call stack. The default 
scope search list is 0,1,2, ...,n, where n is the number 
of calls in the call stack. 

\ Specifies the global scope—that is, the set of all program 
locations in which a global symbol is known. The 
definition of a global symbol and the way it is declared 
depends on the language. 

When you specify more than one location parameter, you establish a scope search 

list. If the debugger cannot interpret the symbol using the first parameter, it uses 

the next parameter, and continues using parameters in order of their specification 
until it successfully interprets the symbol or until it exhausts the parameters 
specified. 

Qualifiers 
/CURRENT 


Establishes a scope search list that is like the default search list (0,1,2, ... ,n) 
but starts at the numeric scope specified as the command parameter. Scope 0 is 
the PC scope, and n is the number of calls in the call stack. 
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Description 


Debugger Command Dictionary 
SET SCOPE 


When using SET SCOPE/CURRENT, note the following conventions and behavior: 


¢ The default scope search list must be in effect when the command is entered. 
To restore the default scope search list, enter the command CANCEL SCOPE. 


¢ The command parameter specified must be one (and only one) decimal integer 
from 0 to n. 


¢ In screen mode, the command updates the predefined source and instruction 
displays SRC and INST, respectively, to show the routine on the call stack in 
which symbol searches are to start. 


¢ The default scope search list is restored when program execution is resumed. 


/MODULE 

Indicates that the name specified as the command parameter is a module name 
and not a routine name. You need to use (MODULE only if you specify a module 
name as the command parameter and that module name is the same as the name 
of a routine. . 


By default, the debugger looks up a symbol specified without a pathname prefix 
according to the scope search list 0,1,2, ... ,n, where n is the number of calls 

in the call stack. This scope search list is based on the current PC value and 
changes dynamically as the program executes. The default scope search list 
specifies that a symbol lookup such as "EXAMINE X first looks for X in the 
routine that is currently executing (scope 0); if no X is visible there, the debugger 
looks in the caller of that routine (scope 1), and so on down the call stack; if X is 
not found in scope n, the debugger searches the rest of the run-time symbol table 
(RST)—that is, all set modules and the global symbol table (GST), if necessary. 


In most cases, this default scope search list enables you to resolve ambiguities 
in a predictable, natural way that is consistent with language rules. But if you 
cannot access a symbol that is defined multiple times, use either of the following 
techniques: 


¢ Specify the symbol with a pathname prefix. The pathname prefix consists 
of any nesting program units (for example, module\ routine \ block) that are 
necessary to specify the symbol uniquely. For example: 


DBG> EXAMINE MOD4\ROUT3\X 
DBG> TYPE MOD4\27 
¢ Establish a new default scope (or a scope search list) for symbol lookup by 
means of the SET SCOPE command. You can then specify the symbol without 
using a pathname prefix. For example: 
DBG> SET SCOPE MOD4\ROUT3 
DBG> EXAMINE X 
DBG> TYPE 27 
The SET SCOPE command is useful in those cases where otherwise you would 
need to use a pathname repeatedly to specify symbols. 


To restore the default scope search list, use the CANCEL SCOPE command. 


When the default scope search list is in effect, you can use the command SET 
SCOPE/CURRENT to specify that symbol searches start at a numeric scope other 
than scope 0, relative to the call stack (for example, scope 2). 
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SET SCOPE 


Examples 
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When you use the SET SCOPE command, the debugger searches only the 
program locations you specify explicitly, unless you use the /CURRENT qualifier. 
Also, the scope or scope search list established with a SET SCOPE command 
remains in effect until you restore the default scope search list or enter another 
SET SCOPE command. However, if you use the /CURRENT qualifier, the default 
scope search list is restored whenever program execution is resumed. 


The SET SCOPE command updates a screen-mode source or instruction display 
only if the command is used with the /CURRENT qualifier. 


If a name you specify in a SET SCOPE command is the name of both a module 
and a routine, the debugger sets the scope to the routine. In such cases, use the 
SET SCOPE/MODULE command if you want to set the scope to the module. 


If you specify a module name in a SET SCOPE command, the debugger "sets" 
that module if it is not already set. However, if you want only to set a module, 
use the SET MODULE command rather than the SET SCOPE command, to avoid 
the possibility of disturbing the current scope search list. 


See Section E.1.12 and Section E.1.13 for information specific to Ada programs. 
Related commands: 


CANCEL ALL 

SEARCH 

SET MODULE 
(SHOW,CANCEL) SCOPE 
SHOW SYMBOL 
SYMBOLIZE 

TYPE 


1.. DBG> EXAMINE Y 
SDEBUG-W-NOUNIQUE, symbol ’Y’ is not unique 
DBG> SHOW SYMBOL Y 
data CHECK_IN\Y 
data INVENTORY\COUNT\Y 
DBG> SET SCOPE INVENTORY\COUNT 
DBG> EXAMINE Y 
INVENTORY\COUNT\Y: 347.15 
DBG> 


In this example, the first EXAMINE Y command indicates that symbol Y is 
defined multiple times and cannot be resolved from the current scope search 
list. The SHOW SYMBOL command displays the different declarations of 
symbol Y. The SET SCOPE command directs the debugger to look for symbols 
without pathname prefixes in routine COUNT of module INVENTORY. The 
subsequent EXAMINE command can now interpret Y unambiguously. 


2. DBG> CANCEL SCOPE 
DBG> SET SCOPE/CURRENT 1 


In this example, the CANCEL SCOPE command restores the default scope 
search list (0,1,2,...,n). The SET SCOPE/CURRENT command then 
changes the scope search list to 1,2, ... ,n, so that symbol searches start with 
scope 1—that is, with the caller of the routine in which execution is currently 
suspended. The predefined source and instruction displays SRC and INST, 
respectively, are updated and now show the source and instructions for the 
caller of the routine in which execution is suspended. 


Debugger Command Dictionary 
SET SCOPE 


DBG> SET SCOPE 1 
DBG> EXAMINE %R5 


In this example, the SET SCOPE command directs the debugger to look for 
symbols without pathname prefixes in scope 1—that is, in the caller of the 
routine in which execution is suspended. The EXAMINE command then 
displays the value of register R5 in the caller routine. The SET SCOPE 
command, when used without the /CURRENT qualifier, does not update any 
source or instruction display. 


DBG> SET SCOPE 0, STACKS\R2, SCREEN 


This command directs the debugger to look for symbols without pathname 
prefixes according to the following scope search list. First the debugger looks 
in the PC scope (denoted by "0"). If the debugger cannot find a specified 
symbol in the PC scope, it then looks in routine R2 of module STACKS. If 
necessary, it then looks in module SCREEN. If the debugger still cannot find 
a specified symbol, it looks no further. 


DBG> SHOW SYMBOL X 


data ALPHA\X ! global X 
data ALPHA\BETA\X ! local X 
data X (global) ! same as ALPHA\X 


DBG> SHOW SCOPE 

scope: 0 [ = ALPHA\BETA ] 

DBG> SYMBOLIZE X 

address ALPHA\BETA\3R0: 
ALPHA\BETA\X 

DBG> SET SCOPE \ 

DBG> SYMBOLIZE X 

address 00000200: 
ALPHA\X 

address 00000200: (global) 
X 

DBG> 


In this example, the SHOW SYMBOL command indicates that there are 
two declarations of the symbol X—a global ALPHA\X (shown twice) and a 
local ALPHA\ BETA\ X. Within the current scope, the local declaration of X 
(ALPHA\ BETA\X) is visible. After the scope is set to the global scope (SET 
SCOPE \), the global declaration of X is made visible. 
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SET SEARCH 


Format 


Parameters 


Description 


Establishes default qualifiers (/ALL or /NEXT, /IDENTIFIER or /STRING) for the 
SEARCH command. 


SET SEARCH §search-default[, ... ] 


search-default 
Specifies a default to be established for the SEARCH command. Valid keywords 
(which correspond to SEARCH command qualifiers) are as follows: 


ALL Subsequent SEARCH commands are treated as SEARCH/ALL, 
rather than SEARCH/NEXT. 


IDENTIFIER Subsequent SEARCH commands are treated as SEARCH 
AIDENTIFIER, rather than SEARCH/STRING. 


NEXT Subsequent SEARCH commands are treated as SEARCH/NEXT, 
rather than SEARCH/ALL. This is the default. 

STRING Subsequent SEARCH commands are treated as SEARCH 
/STRING, rather than SEARCH/IDENTIFIER. This is the 
default. 


The SET SEARCH command establishes default qualifiers for subsequent 
SEARCH commands. The parameters that you specify in the SET SEARCH 


- command have the same names as the SEARCH command qualifiers. The 
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qualifiers determine whether the SEARCH command: (1) searches for all 
occurrences (ALL) of a string or only the next occurrence (NEXT); and (2) 
displays any occurrence of the string (STRING) or only those occurrences in 
which the string is not bounded on either side by a character that can be part of 
an identifier in the current language (IDENTIFIER). 


You can override the current SEARCH default for the duration of a single 
SEARCH command by specifying other qualifiers. Use the SHOW SEARCH 
command to identify the current SEARCH defaults. 


Related commands: 


SEARCH 
(SET,SHOW) LANGUAGE 
SHOW SEARCH 


Example 


Debugger Command Dictionary 
SET SEARCH 


DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 
DBG> SET SEARCH IDENTIFIER 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 

DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 
DBG> 


In this example, the SET SEARCH IDENTIFIER command directs the debugger 
to search for an occurrence of the string in the specified range but display the 
string only if it is not bounded on either side by a character that can be part of 
an identifier in the current language. 


The SET SEARCH ALL command directs the debugger to search for (and display) 
all occurrences of the string in the specified range. 
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SET SOURCE 


Format 


Parameters 


Qualifiers 


Specifies where the debugger is to search for source files that have been moved to 
another directory after being compiled. 


SET SOURCE directory-speci, ... ] 


directory-spec 

Specifies any part of a VMS file specification (typically a device/directory) that 
the debugger is to use by default when searching for a source file. For any 
part of a full file specification that you do not supply, the debugger uses the file 
specification stored in the module’s symbol record—that is, the file specification 
that the source file had at compile time. 


If you specify more than one directory in a single SET SOURCE command, you 
create a source directory search list (you can also specify a search list logical 
name that is defined at your process level). In this case, the debugger locates the 
source file by searching the first directory specified, then the second, and so on, 
until it either locates the source file or exhausts the list of directories. 


_ JEDIT 


Description 
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Applies mainly to Ada programs. 


Specifies that the directory search list is used to locate source files for editing 
when you use the EDIT command. 


/MODULE=module-name 
Specifies that the directory search list is used to locate source files only for the 
specified module. 


By default, the debugger expects a source file to be in the same directory it was 
in at compile time (the debugger also checks that the creation and revision date 
and time of a source file match the information in the debugger’s symbol table). 
If a source file has been moved to a different directory since compile time, use the 
SET SOURCE command to specify a source directory search list. 


When a source file is moved to another directory, the version number of the source 
file might change. To locate the correct version of the source file in the event that 
a version number was not specified in the directory-spec parameter, the debugger 
inserts the match-all asterisk (*) wildcard character in the version number field 
of the new file specification. Therefore, all versions of the moved source file are 
searched until the correct version is located. The correct version of the source 
file is the version that has the same creation or revision date and time, the same 
file size, the same record format, and the same file organization as the original 
compile-time source file. 


Examples 


Debugger Command Dictionary 
SET SOURCE 


If the debugger does not find the correct version, it uses the file that has the 
closest revision date and time (if such a file exists in that directory) and issues a 
message such as the following when first displaying source code: 


SDEBUG-I-NOTORIGSRC, original version of source file not found 
file used is WORK: [JONES.PROG3] PRG.FOR;14 


If you enter the SET SOURCE command without the /MODULE=module-name 
qualifier, the debugger uses the specified directory search list to locate source 
files for all modules that were not mentioned in a previous SET SOURCE 
/MODULE=module-name command. 


See the qualifier descriptions for an explanation of their effects. 


The /EDIT qualifier is needed when the files used for the display of source code 
are different from the files to be edited by means of the EDIT command. This 

is the case with Ada programs. For Ada programs, the (SET, SHOW, CANCEL) 
SOURCE commands affect the search of files used for source display (the "copied" 
source files in Ada program libraries); the (SET,SHOW,CANCEL) SOURCE/EDIT 
commands affect the search of the source files you edit when using the EDIT 
command. If you use (MODULE with /EDIT, the effect of /EDIT is further 
qualified by (MODULE. 


See Section E.1.5 and Section E.1.6 for information specific to Ada programs. 
A full VMS file specification consists of the following fields: 
node::device:[directory]file-name.file-type;version-number 


If the full file specification of a source file exceeds 231 characters, the debugger 
cannot locate the file. You can work around this problem by first defining a logical 
name "X" (at DCL level) to expand to your long file specification, and then using 
the command "SET SOURCE Xr. 


When compiling a program with the /DEBUG qualifier, if you use a rooted- 
directory logical name to specify the location of the source file, make sure that it 
is a concealed rooted-directory logical name. If it is not concealed and you move 
the source file to another directory after compilation, you cannot then use the 
debugger SET SOURCE command to specify the new location of the source file. 


To create a concealed rooted-directory logical name, use the syntax illustrated in 
the following example: 


$ DEFINE/TRANSLATION ATTR=CONCEAL ROOTDIR DISK3$: [USER.DIR1.] 
Related commands: 


(CANCEL,SHOW) MAX_SOURCE_FILES 
(CANCEL,SHOW) SOURCE 


1. DBG> SHOW SOURCE 

no directory search list in effect 

DBG> SET SOURCE [PROJA], [PROJB], USER$: [PETER.PROJC] 

DBG> SHOW SOURCE 

source directory search list for all modules: 
[PROJA] 
[PROJB] 
USERS: [PETER.PROJC] 

DBG> 
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In this example, the SET SOURCE command specifies that the debugger 
should search directories [PROJA], [PROJB], and USER$:[PETER.PROJC], in 
that order, for source files. 


DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2: [PROJD] 
DBG> SHOW SOURCE 
source directory search list for COBOLTEST: 

(] 


DISK$2: [PROUD] 
source directory search list for all other modules: 
[PROJA] 
[PROJB] 
USERS: [PETER.PROJC] 
DBG> 


In this example, the SET SOURCE command specifies that the debugger 
should search the current default directory ({]) and DISK$2:[PROJD], in 
that order, for source files to use with the module COBOLTEST. The SHOW 
SOURCE command displays the search lists established in examples 1 and 2. 


SET STEP 


Format 


Parameters 


Debugger Command Dictionary 
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Establishes default qualifiers (LINE, /INTO, and so on) for the STEP command. 


SET STEP  step-defauli[, ... ] 


step-default 


Specifies a default to be established for the STEP command. Valid keywords 
(which correspond to STEP command qualifiers) are as follows: 


BRANCH 


CALL 


EXCEPTION 


INSTRUCTION 


INTO 


JSB 


NOJSB 


LINE 


OVER 


Subsequent STEP commands are treated as STEP/BRANCH 
(step to the next branch instruction). 


Subsequent STEP commands are treated as STEP/CALL (step 
to the next call instruction). 


Subsequent STEP commands are treated as STEP 
/EXCEPTION (step to the next exception). 


Subsequent STEP commands are treated as STEP 
ANSTRUCTION (step to the next instruction). 

You can also specify one or more instructions 
(ANSTRUCTION[=(opcode ... )]). The debugger then steps to 
the next instruction that is in the specified list. If you specify 
a vector instruction, do not include an instruction qualifier (/U, 
/V, /M, /0, or /1) with the instruction mnemonic. 


Subsequent STEP commands are treated as STEP/INTO 
(step into called routines) rather than STEP/OVER (step over 
called routines). When INTO is in effect, you can qualify 

the types of routines to step into by means of the [NO]JSB, 
[NO]JSHARE, and [NO]JSYSTEM parameters, or by using the 
STEP/[NO]JSB, STEP/[NO]JSHARE, and STEP/INO]SYSTEM 
command/qualifier combinations (the latter three take effect 
only for the immediate STEP command). 

If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/JSB (step into routines called by a JSB 
instruction as well as those called by a CALL instruction). 
This is the default for all languages except DIBOL. 

If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/NOJSB (step over routines called by a 

JSB instruction, but step into routines called by a CALL 
instruction). This is the default for DIBOL. 

Subsequent STEP commands are treated as STEP/LINE (step 
to the next line). This is the default for all languages. 


Subsequent STEP commands are treated as STEP/OVER (step 
over all called routines) rather than STEP/INTO (step into 
called routines). SET STEP OVER is the default. 
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RETURN 


SHARE 


NOSHARE 


SILENT 


NOSILENT 


SOURCE 


NOSOURCE 


SYSTEM 


NOSYSTEM 


VECTOR_ 


INSTRUCTION 


Description 


_ Subsequent STEP commands are treated as STEP/RETURN 


(step to the RET instruction of the routine that is currently 
executing—that is, up to the point just prior to transferring 
control back to the calling routine). 


If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/SHARE (step into called routines in shareable 
images as well as into other called routines). This is the 
default. 


If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/NOSHARE (step over called routines in 
shareable images, but step into other routines). 


Subsequent STEP commands are treated as STEP/SILENT 
(after a step, do not display the "stepped to ... " message or 
the source line for the current location). 


Subsequent STEP commands are treated as STEP/NOSILENT 
(after a step, display the "stepped to ... " message). This is 
the default. 


Subsequent STEP commands are treated as STEP/SOURCE 
(after a step, display the source line for the current location). 
Also, subsequent SET BREAK, SET TRACE, and SET WATCH 
commands are treated as SET BREAK/SOURCE, SET TRACE 
/SOURCE, and SET WATCH/SOURCE, respectively (at a 
breakpoint, tracepoint, or watchpoint, display the source line 
for the current location). This is the default. 


Subsequent STEP commands are treated as STEP 
/NOSOURCE (after a step, do not display the source line 

for the current location). Also, subsequent SET BREAK, 

SET TRACE, and SET WATCH commands are treated as 
SET BREAK/NOSOURCE, SET TRACE/NOSOURCE, and 
SET WATCH/NOSOURCE, respectively (at a breakpoint, 
tracepoint, or watchpoint, do not display the source line for the 
current location). 


If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/SYSTEM (step into called routines in system 
space (P1 space) as well as into other called routines). This is 
the default. 


If INTO is in effect, subsequent STEP commands are treated 
as STEP/INTO/NOSYSTEM (step over called routines in 
system space, but step into other routines). 


Subsequent STEP commands are treated as STEP/VECTOR_ 
INSTRUCTION (step to the next vector instruction). 


The SET STEP command establishes default qualifiers for subsequent STEP 
commands. The parameters that you specify in the SET STEP command have the | 
same names as the STEP command qualifiers. The following parameters affect 
where the STEP command suspends execution after a step: 


BRANCH 


CALL 


EXCEPTION 


INSTRUCTION[=(opcode[, .. . ])] 
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SET STEP 


LINE 
RETURN 
VECTOR_INSTRUCTION 


The following parameters affect what output is seen when a STEP command is 
executed: 


[NO]SILENT 
[NO]JSOURCE 


The following parameters affect what happens at a routine call: 


INTO 
[NO]JSB 
OVER 
[NO]JSHARE 
[NO]SYSTEM 


You can override the current STEP defaults for the duration of a single STEP 
command by specifying other qualifiers. Use the SHOW STEP command to 
identify the current STEP defaults. 


If you invoke screen mode with the keypad-key sequence PF1-PF3, the command 
SET STEP NOSOURCE is entered in addition to the command SET MODE 
SCREEN. Therefore, any display of source code in output and DO displays 

that would result from a STEP command or from a breakpoint, tracepoint, or 
watchpoint being triggered is suppressed, to eliminate redundancy with the 
source display. 


Related commands: 


SHOW STEP 
STEP 


1. DBG> SET STEP INSTRUCTION, NOSOURCE 


This command causes the debugger to execute the program to the next 
instruction when a STEP command is entered, and not to display lines of 
source code with each STEP command. 


2. DBG> SET STEP LINE, INTO, NOSYSTEM, NOSHARE 


This command causes the debugger to execute the program to the next 
line when a STEP command is entered, and to step into called routines in 
user space only. The debugger steps over routines in system space and in 
shareable images. 
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SET TASK 


Format 


Parameters 


Qualifiers 
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Changes characteristics of one or more tasks of a tasking program (also called a 
multithread program). 


SET TASK [task-spec[, ... J] 


task-spec 
Specifies a task value. Use any of the following forms: 


e A task (thread) name as declared in the program, or a language expression 
that yields a task value. You can use a pathname. 


e¢ A task ID (for example, 2TASK 2), as indicated in a SHOW TASK display. 


© One of the following task built-in symbols: 


%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or 
EXIT command executes. 
%CALLER_TASK (Applies only to Ada programs.) When an accept 


statement executes, the task that called the entry 
associated with the accept statement. 


%NEXT_TASK The task after the visible task in the debugger’s 
task list. The ordering of tasks is arbitrary but 
consistent within a single run of a program. 


%PREVIOUS_TASK The task previous to the visible task in the 
debugger’s task list. 


%VISIBLE_TASK The task whose call stack and register set are the 
current context for looking up symbols, register 
values, routine calls, breakpoints, and so on. 


Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. 
For details on how to specify tasks with particular qualifiers, see the qualifier 
descriptions. If you do not specify a task with the /ABORT, /[NOJHOLD, 
/PRIORITY, or /RESTORE qualifier, the visible task is selected. 


/ABORT 

Marks the specified tasks for termination. Termination occurs at the next 
allowable point after a specified task resumes execution. If no task is specified, 
marks the visible task for termination. 


For Ada tasks, the effect is identical to executing an Ada abort statement for the 
tasks specified and causes these tasks to be marked as abnormal. Any dependent 
tasks are also marked for termination. 


For DECthreads threads, the effect is identical to doing an alert operation for the 
threads specified. Only the specified threads are marked for termination. 
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/ACTIVE 

Makes the specified task the active task—the task that runs when a STEP, GO, 
CALL, or EXIT command executes. Causes a task switch to the new active task 
and makes that task the visible task. The specified task must be in either the 
RUNNING or READY state. When using /ACTIVE, you must specify one task. 


/ALL 
Applies the SET TASK command to all tasks. Do not specify a task or the 
/ACTIVE, /VISIBLE, or /TIME_SLICE qualifiers with /ALL. 


/HOLD 

/NOHOLD 

Controls whether a specified task is put on hold. The /HOLD qualifier puts a 
specified task on hold. If no task is specified, /HOLD puts the visible task on 
hold. 


Putting a task on hold prevents a task from entering the RUNNING state. A 
task put on hold is allowed to make other state transitions; in particular, it can 
change from the SUSPENDED to the READY state. 


A task already in the RUNNING state (the active task) can continue to execute 
as long as it remains in the RUNNING state, even though it is put on hold. If the 
task leaves the RUNNING state for any reason (including expiration of a time 
slice, if time slicing is enabled), it will not return to the RUNNING state until 
released from the hold condition. 


You can override the hold condition and force a task into the RUNNING state 
with the SET TASK/ACTIVE command even if the task is on hold. 


The /NOHOLD qualifier releases a specified task from hold. If no task is specified, 
/NOHOLD releases the visible task from hold. 


/PRIORITY=n 

Sets the priority of a specified task to n, where n is a decimal integer from 0 to 15. 
This does not prevent the priority from later changing in the course of execution, 
for example while executing an Ada rendezvous or DECthreads synchronization 
event. 


The /PRIORITY qualifier does not affect a task’s scheduling policy. 
If no task is specified, /PRIORITY sets the priority of the visible task to n. 


/RESTORE 
Restores the priority of a specified task to the priority it had when it was created. 
Does not affect the scheduling priority of the task. 


/TIME_SLICE=t 

Sets the time-slice duration to the value ¢, where ¢ is a decimal integer or real 
value representing seconds. The set value overrides the time-slice value specified 
in the program, if any. 


To disable time slicing, use the SET TASK/TIME_SLICE=0.0 command. 


/VISIBLE 

Makes the specified task the visible task—the task whose call stack and register 
set are the current context for looking up symbols, register values, routine 
calls, breakpoints, and so on. Commands such as EXAMINE are directed at the 
visible task. The /VISIBLE qualifier does not affect the active task. When using 
/VISIBLE, you must specify one task. 
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The SET TASK command enables you to establish the visible task and the active 
task, control the execution of tasks, and cause task state transitions, directly or 
indirectly. 


To determine the current state of a task, use the SHOW TASK command. The » 
possible states are RUNNING, READY, SUSPENDED, and TERMINATED. 


Related commands: 


DEPOSIT/TASK 
EXAMINE/TASK 
SET BREAK/EVENT 
SET TRACE/EVENT 
SHOW TASK 


1. DBG> SET TASK/ACTIVE $TASK 3 
This command makes task 3 (task ID = 3) the active task. 


2. DBG> SET TASK SNEXT TASK 


This command makes the next task in the debugger’s task list the visible 
task. (The /VISIBLE qualifier is a default for the SET TASK command.) 


3. DBG> SET TASK/HOLD/ALL 
DBG> SET TASK/ACTIVE %TASK 1 
DBG> GO 


DBG> SET TASK/ACTIVE %TASK 3 
DBG> STEP 


The SET TASK/HOLD/ALL command freezes the state of all tasks except the 
active task. Then, SET TASK/ACTIVE is then used selectively (along with 
the GO and STEP commands) to observe the behavior of one or more specified 
tasks in isolation. 
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SET TERMINAL 


Format 


Qualifiers 


Description 


Sets the terminal-screen height or width that the debugger uses when it formats 
screen and other output. 


SET TERMINAL 


You must specify at least one qualifier, either /PAGE or /WIDTH. You can specify 
both /PAGE and /WIDTH. You must specify a value for each qualifier used. 


/PAGE:n 
Specifies that the terminal screen height should be set to n lines. You can use 
any value from 18 to 100. 


/WIDTH:n 

Specifies that the terminal screen width should be set to n columns. You can use 
any value from 20 to 255. For a VT100- , VT200- , or VT'300-series terminal, n is 
typically either 80 or 132. 


The SET TERMINAL command enables you to define the portion of the screen 
that the debugger has available for formatting screen output. 


This command is useful with VT100-, VT200-, or VT300-series terminals, where 
you can set the screen width to typically 80 or 1382 columns. It is also useful with 
workstations, where you can modify the size of the terminal-emulator window 
that the debugger uses. 


When you enter the SET TERMINAL command, all screen window definitions 
(including those created by the user) are automatically adjusted for the new 
screen dimensions. For example, RH1 changes dimensions proportionally to 
remain the top right half of the screen. 


Similarly, all "dynamic" displays are automatically adjusted to maintain their 
relative dimensions. By default, all predefined and user-defined displays are 
dynamic. If you have specified /(NODYNAMIC in a DISPLAY command, the 
display is no longer dynamic. In that case, the display does not automatically 


‘change dimensions with a SET TERMINAL command. However, you can always 


use the DISPLAY command to redisplay the display within any window definition 
(you can also use keypad-key combinations, such as BLUE-MINUS, to enter 
predefined DISPLAY commands). 


Related commands: 


DISPLAY/[NO]DYNAMIC 
EXPAND 

(SET,SHOW,CANCEL) WINDOW 
SHOW TERMINAL 
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Example 


DBG> SET TERMINAL/WIDTH:132 


This command specifies that the terminal screen width be set to 132 columns. 
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SET TRACE 


Format 


Parameters 
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SET TRACE 


Establishes a tracepoint at the location denoted by an address expression, at 
instructions of a particular class, or at the occurrence of specified events. 


SET TRACE [address-expression[, . . . ]] [WHEN(conditional-expression)] 
[DO(command]; . . . ])] 


address-expression 

Specifies an address expression (a program location) at which a tracepoint is 

to be set. With high-level languages, this is typically a line number, a routine 
name, or a label, and can include a pathname to specify the entity uniquely. 
More generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the operators that can 
be used in address expressions. 


Do not specify the asterisk (*) wildcard character. Do not specify an address 
expression with the following qualifiers: 


/ACTIVATING 

/BRANCH 

/CALL 

/EXCEPTION 
ANNSTRUCTION[=(opcode ... )] 
INTO 

/[NO]JSB 

/LINE 

/OVER 

/[INO]JSHARE 
/[NO]SYSTEM 
/TERMINATING 
/VECTOR_INSTRUCTION. 


The /MODIFY and /RETURN qualifiers are used with specific kinds of address 
expressions. 


If you specify a memory address or an address expression whose value is not 

a symbolic location, check (with the EXAMINE command) that an instruction 
actually begins at the byte of memory so indicated. If an instruction does not 
begin at this byte, a run-time error can occur when an instruction including that 
byte is executed. When you set a tracepoint by specifying an address expression 
whose value is not a symbolic location, the debugger does not verify that the 
location specified marks the beginning of an instruction. CALLS and CALLG 
routines start with an entry mask. 


conditional-expression 

Specifies a conditional expression in the currently set language that is to be 
evaluated whenever execution reaches the tracepoint. If the expression is true, 
trace action occurs, and the debugger reports that a tracepoint has been reached. 
If the expression is false, trace action does not occur. In this case, a report is not 
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issued, the commands specified by the DO clause are not executed, and program 
execution is continued. 


command . 
Specifies a debugger command to be executed as part of the DO clause when trace 
action is taken. 


/ACTIVATING 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). 


Causes the debugger to trace when a new process comes under debugger 
control. This is the default behavior. Do not specify an address expression 
with /ACTIVATING. See also /TERMINATING. 


/AFTER:zn - 

Specifies that trace action not be taken until the nth time the designated 
tracepoint is encountered (7 is a decimal integer). Thereafter, the tracepoint 
occurs every time it is encountered provided that conditions in the WHEN clause 
(if specified) are true. The SET TRACE/AFTER:1 command has the same effect 
as the SET TRACE command. 


/BRANCH 
Causes the debugger to trace every branch instruction encountered during 


program execution. Do not specify an address expression with /BRANCH. See 
also INTO and /OVER. 


ICALL 

Causes the debugger to trace every call instruction encountered during program 
execution, including the RET instruction. Do not specify an address expression 
with /CALL. See also [NTO and /OVER. 


/EVENT=event-name 

Causes the debugger to trace the specified event (if that event is defined and 
detected by the current event facility). If you specify an address expression with 
/EVENT, causes the debugger to trace whenever the specified event occurs for 
that address expression. You cannot specify an address expression with certain 
event names. 


Event facilities are available for programs that call Ada or SCAN routines or that 
use DECthreads services. To identify the current event facility and the associated 
event names, use the SHOW EVENT_FACILITY command. 


/EXCEPTION 

Causes the debugger to trace every exception that is signaled. The trace action 
occurs before any application-declared exception handlers are invoked. Do not 
specify an address expression with /EXCEPTION. 


As a result of a SET TRACE/EXCEPTION command, whenever your program 
generates an exception, the debugger reports the exception and resignals the 
exception, thus allowing any application-declared exception handler to execute. 
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/INSTRUCTION[=(opcode[, . . . ])] 

If you do not specify an opcode, causes the debugger to trace every instruction 
encountered during program execution. If you specify one or more opcodes, causes 
the debugger to trace every instruction whose opcode is in the list. 


Do not specify an address expression with this qualifier. If you specify a vector 
instruction, do not include an instruction qualifier (/U, /V, /M, /0, or /1) with the 
instruction mnemonic. See also /INTO and /OVER. 


/INTO 
Applies only to tracepoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: 


/BRANCH 

/CALL 

AINSTRUCTION[=(opcodel, . . . 1))) 
/LINE 

/VECTOR_INSTRUCTION 


When used with those qualifiers, causes the debugger to trace the specified 
points within called routines (as well as within the routine in which execution 
is currently suspended). The /INTO qualifier is the default behavior and is the 
opposite of /OVER. 


When using /INTO, you can further qualify the trace action with the /[NO]JSB, 
/[NOISHARE, and /[NO]SYSTEM qualifiers. 


/JSB 

/NOJSB 

Qualifies INTO. Use /[NO]JSB only with ANTO and one of the following 
qualifiers: 


/BRANCH 

/CALL 
AINSTRUCTION[=(opcode .. . )] 
/LINE 
/VECTOR_INSTRUCTION 


The /JSB qualifier is the default for all languages except DIBOL. The /JSB 
qualifier permits the debugger to set tracepoints within routines that are called 
by the JSB or CALL instruction. The /NOJSB qualifier (the DIBOL default) 
specifies that tracepoints not be set within routines called by JSB instructions. 
In DIBOL, application-declared routines are called by the CALL instruction and 
DIBOL run-time library routines are called by the JSB instruction. Do not specify 
an address expression with /[NO]JSB. 


/LINE 

Causes the debugger to trace the beginning of each source line encountered 
during program execution. Do not specify an address expression with /LINE. See 
also /INTO and /OVER. 


/MODIFY 

Causes the debugger to trace when an instruction writes to and changes the value 
of a location indicated by a specified address expression. The address expression 
is typically a variable name. 


The SET TRACE/MODIFY X command is equivalent to the SET WATCH X 
DO(GO) command. SET TRACE/MODIFY operates under the same restrictions 
as SET WATCH. 
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If you specify an absolute address for the address expression, the debugger might 
not be able to associate the address with a particular data object. In this case, the 
debugger uses a default length of 4 bytes. You can change this length, however, 
by setting the type to either WORD (SET TYPE WORD, which changes the 
default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the default 
length to 1 byte). SET TYPE LONGWORD restores the default length of 4 bytes. 


/OVER 
Applies only to tracepoints set with the following qualifiers—that is, when an 
address expression is not explicitly specified: 


/BRANCH 

/CALL 
AINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 


When used with those qualifiers, causes the debugger to trace the specified 
points only within the routine in which execution is currently suspended (not 
within called routines). The /OVER qualifier is the opposite of /INTO (the default 
behavior). 


/RETURN 

Causes the debugger to trace the RET (return) instruction of the routine 
associated with the specified address expression (which can be a routine name, 
line number, and so on). This qualifier can only be applied to routines called with 
a CALLS or CALLG instruction; it cannot be used with JSB routines. Tracing the 
RET instruction enables you to inspect the local environment (for example, obtain 
the values of local variables) before the RET instruction deletes the routine’s call 
frame from the call stack. 


For this qualifier, the address-expression parameter is an instruction address 
within a CALLS or CALLG routine. It can simply be a routine name, in which 
case it specifies the routine start address. However, you can also specify another 
location in a routine, so you can see only those returns that are taken after a 
certain code path is followed. 


A SET TRACE/RETURN command cancels a previous SET TRACE command if 
the same address expression is specified. 


/SHARE (default) 
/NOSHARE 

Qualifies INTO. Use /[NO]SHARE only with /INTO and one of the following 
qualifiers: 


/BRANCH 

/CALL 
AINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION . 


The /SHARE qualifier permits the debugger to set tracepoints within shareable 
image routines as well as other routines. The /NOSHARE qualifier specifies 
that tracepoints not be set within shareable images. Do not specify an address 
expression with /[NO|SHARE. 


Description 
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SET TRACE 
/SILENT 
/NOSILENT (default) 
Controls whether the "trace ... " message and the source line for the current 


location are displayed at the tracepoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
source line are not displayed. The /SILENT qualifier overrides /SOURCE. 


/SOURCE (default) 

/NOSOURCE 

Controls whether the source line for the current location is displayed at the 
tracepoint. The /SOURCE qualifier specifies that the source line is displayed. 
The /NOSOURCE qualifier specifies that the source line is not displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NOJSOURCE. 


/SYSTEM (default) 

/NOSYSTEM 

Qualifies /INTO. Use /[NO]SYSTEM only with /INTO and one of the following 
qualifiers: 


/BRANCH 

/CALL 
AINSTRUCTION[=(opcode ... )] 
/LINE 
/VECTOR_INSTRUCTION 


The /SYSTEM qualifier permits the debugger to set tracepoints within system 
routines (P1 space) as well as other routines. The /NOSYSTEM qualifier specifies 
that tracepoints not be set within system routines. Do not specify an address 
expression with /[NOJSYSTEM. 


/TEMPORARY 
Causes the tracepoint to disappear after it is triggered (the tracepoint does not 
remain permanently set). 


/TERMINATING 

Causes the debugger to trace when a process does an image exit. This is the 
default behavior. The debugger always gains control and displays its prompt 
when the last image of a one-process or multiprocess program exits. Do not 

specify an address expression with /TERMINATING. See also /ACTIVATING. 


/VECTOR_INSTRUCTION 

Causes the debugger to trace every vector instruction encountered during 
program execution. Do not specify an address expression with /VECTOR_ 
INSTRUCTION. See also INTO and /OVER. 


When a tracepoint is triggered, the debugger takes the following action: 
1. Suspends program execution at the tracepoint location. 


2. If/AFTER was specified when the tracepoint was set, checks the AFTER 
count. If the specified number of counts has not been reached, execution is 
resumed and the debugger does not perform the remaining steps. 


3. Evaluates the expression in a WHEN clause, if one was specified when 
the tracepoint was set. If the value of the expression is false, execution is 
resumed and the debugger does not perform the remaining steps. 
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4. Reports that execution has reached the tracepoint location by issuing a 
"trace ... " message, unless /SILENT was specified. 


5. Displays the line of source code corresponding to the tracepoint, unless 
/NOSOURCE or /SILENT was specified when the breakpoint was set, or SET 
STEP NOSOURCE was entered previously. 


6. Executes the commands in a DO clause, if one was specified when the 
tracepoint was set. 


7. Resumes execution. 


You set a tracepoint at a particular location in your program by specifying an 
address expression with the SET TRACE command. You set a tracepoint on 
consecutive source lines, classes of instructions, or events by specifying a qualifier 
with the SET TRACE command. Generally, you must specify either an address 
expression or a qualifier, but not both. Exceptions are the /EVENT and /RETURN 
qualifiers. 


The /LINE qualifier sets a tracepoint on each line of source code. 


The following qualifiers set tracepoints on classes of instructions. Use of 
these qualifiers and of the /LINE qualifier causes the debugger to trace every 
instruction of your program as it executes and thus significantly slows down 
execution: 


/BRANCH 

/CALL 
AINSTRUCTION|[=(opcode[, .. . ])] 
/RETURN 
/VECTOR_INSTRUCTION 


The following qualifiers set tracepoints on classes of events: 


/ACTIVATING 
/EVENT=event-name 
/EXCEPTION 
/TERMINATING 


The following qualifiers affect what happens at a routine call: 


AINTO 
/[NO]JSB 
/OVER 
/[NOJSHARE 
/[NO]JSYSTEM 


The following qualifiers affect what output is displayed when a tracepoint is 
reached: 


/[NO]SILENT 
/[NO|ISOURCE 


The following qualifiers affect the timing and duration of tracepoints: 


/AFTER:n 
/TEMPORARY 


The /MODIFY qualifier is used to monitor changes at program locations (typically 
changes in the values of variables). 


If you set a tracepoint at a location currently used as a breakpoint, the breakpoint 
is canceled in favor of the tracepoint, and conversely. 


Examples 
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Tracepoints can be user defined or predefined. User defined tracepoints are those 
that you set explicitly with the SET TRACE command. Predefined tracepoints, 
which depend on the type of program you are debugging (for example, Ada or 
multiprocess), are established automatically when you invoke the debugger. Use 
the SHOW TRACE command to identify all tracepoints that are currently set. 
Any predefined tracepoints are identified as such. 


User defined and predefined tracepoints are set and canceled independently. 
For example, a location or event can have both a user defined and a predefined 
tracepoint. Canceling the user defined tracepoint does not affect the predefined 
tracepoint, and conversely. 


Related commands: 


CANCEL ALL 

GO 

SET BREAK 

(SET,SHOW) EVENT_FACILITY 
SET STEP [NO]JSOURCE 

SET WATCH 

(SHOW,CANCEL) TRACE 


1. DBG> SET TRACE SUB3 


This command causes the debugger to trace the beginning of routine SUB3 
when that routine is executed. 


2. DBG> SET TRACE/BRANCH/CALL 


This command causes the debugger to trace every BRANCH instruction and 
every CALL instruction encountered during program execution. 


3. DBG> SET TRACE/LINE/INTO/NOSHARE/NOSYSTEM 


This command causes the debugger to trace the beginning of every source 
line, including lines in called routines (INTO) but not in shareable image 
routines ((NOSHARE) or system routines ((NOSYSTEM). 


4, DBG> SET TRACE/NOSOURCE TEST5\%LINE 14 WHEN (X .NE. 2) DO (EXAMINE Y) 


This command causes the debugger to trace line 14 of module TEST5 when 
X is not equal to 2. At the tracepoint, the EXAMINE Y command is issued. 
The /NOSOURCE qualifier suppresses the display of source code at the 
tracepoint. The syntax of the conditional expression in the WHEN clause is 
language-dependent. 


5. DBG> SET TRACE/INSTRUCTION WHEN (X .NE. 0) 


This command causes the debugger to trace when X is not equal to 0. The 
condition is tested at each instruction encountered during execution. The | 
syntax of the conditional expression in the WHEN clause is language- 
dependent. 
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6. 


DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K) 


This command causes the debugger to trace the beginning of routine SUB2 
during execution. At the tracepoint, the DO clause sets a watchpoint on 
variable K. The /SILENT qualifier on the SET TRACE command suppresses 
the "trace ... " message and the display of source code at the tracepoint. 
This example shows a convenient way of setting a watchpoint on a nonstatic 
(stack or register) variable. A nonstatic variable is defined only when its 
defining routine (SUB2, in this case) is active (on the call stack). 


DBG> SET TRACE/RETURN ROUT4 DO (EXAMINE X) 


This command causes the debugger to trace the RET instruction of routine 
ROUT4 (that is, just before execution returns to the calling routine). At: the 
tracepoint, the DO clause issues the EXAMINE X command. This example 
shows a convenient way of obtaining the value of a nonstatic variable just 
before execution leaves that variable’s defining routine. 


DBG> SET TRACE/EVENT=TERMINATED 


This command causes the debugger to trace the point at which any task 
makes a transition to the TERMINATED state. 


SET TYPE 


Format 


Parameters 
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Establishes the default type to be associated with program locations that do 

not have a symbolic name (and, therefore, do not have an associated compiler 
generated type). When used with /OVERRIDE, establishes the default type to be 
associated with all locations, overriding any compiler generated types. 


SET TYPE type-keyword 


type-keyword 
Specifies the default type to be established. Valid keywords are as follows: 


ASCIC Sets the default type to counted ASCII string with a 
1-byte count field that precedes the string and gives 
its length. AC is also accepted as a keyword. 


ASCID Sets the default type to ASCII string descriptor. 
The CLASS and DTYPE fields of the descriptor are 
not checked, but the LENGTH and POINTER fields 
provide the character length and address of the 
ASCII string. The string is then displayed. AD is 
also accepted as a keyword. : 


ASCII:n Sets the default type to ASCII character string 
(length n bytes). The length indicates both the 
number of bytes of memory to be examined and the 
number of ASCII characters to be displayed. If you 
do not specify a value for n, the debugger uses the 
default value of 4 bytes. The value n is interpreted in 
decimal radix. 

ASCIW Sets the default type to counted ASCII string with a 
2-byte count field that precedes the string and gives 
its length. This data type occurs in PASCAL and 
PL/I. AW is also accepted as a keyword. 

ASCIZ Sets the default type to zero-terminated ASCII string. 
The ending zero byte indicates the end of the string. 
AZ is also accepted as a keyword. 

BYTE Sets the default type to byte integer (length 1 byte). 

D_FLOAT Sets the default type to D_floating (length 8 bytes). 
Values of type D_floating can range from .29 * 107°8 
to 1.7 « 10°° with approximately 16 decimal digits 
precision. 
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DATE_TIME 


FLOAT 


G_FLOAT 


H_FLOAT 


INSTRUCTION 
LONGWORD 
OCTAWORD 
PACKED:n 
QUADWORD 


TYPE=(expression) 


WORD 


Qualifiers 
/OVERRIDE 


Sets the default type to date and time. This is a 
quadword integer (length 8 bytes) containing the 
internal VMS representation of date and time. 
Values are displayed in the format dd-mmm-yyyy 
hh:mm:ss.xx. Specify an absolute date and time as 
follows: 


{dd-mmm-yyyy[:]] [hh:mm:ss.cc] 


Sets the default type to F_floating (length 4 bytes). 
Values of type F_floating can range from .29 « 10738 
to 1.7 « 10° with approximately 7 decimal digits 
precision. 


Sets the default type to G_floating (length 8 bytes). 
Values of type G_floating can range from .56 « 10799 
to .9 « 10°08 with approximately 15 decimal digits 
precision. 


Sets the default type to H_floating (length 16 bytes). 
Values of type H_floating can range from .84 « 107499? 
to .59 » 104982 with approximately 33 decimal digits 
precision. 

Sets the default type to VAX instruction (variable 
length, depending on the number of instruction 
operands and the kind of addressing modes used). 
Sets the default type to longword integer (length 4 
bytes). This is the default type for program locations 
that do not have a symbolic name (do not have a 
compiler generated type). 

Sets the default type to octaword integer (length 16 
bytes). 

Sets the default type to packed decimal. The value of 
n is the number of decimal digits. Each digit occupies 
one nibble (4 bits). 

Sets the default type to quadword integer (length 8 
bytes). 

Sets the default type to the type denoted by 
expression (the name of a variable or data type 
declared in the program). This enables you to specify 
an application-declared type. 


Sets the default type to word integer (length 2 bytes). 


Associates the type specified with all program locations, whether or not they have 
a symbolic name (whether or not they have an associated compiler generated 


type). 
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When you use the EXAMINE, DEPOSIT, or EVALUATE commands, the default 
types associated with address expressions influence how the debugger interprets 
and displays program entities. 


The debugger recognizes the compiler generated types associated with symbolic 
address expressions (symbolic names declared in your program), and it interprets 
and displays the contents of these locations accordingly. For program locations 
that do not have a symbolic name and, therefore, no associated compiler 
generated type, the default type in all languages is longword integer. 


The SET TYPE command enables you to change the default type associated 
with locations that do not have a symbolic name. The SET TYPE/OVERRIDE 
command enables you to set a default type for all program locations, both those 
that do and do not have a symbolic name. 


The EXAMINE and DEPOSIT commands have type qualifiers (/ASCII, /BYTE, 
/G_FLOAT, and so on) that enable you to override, for the duration of a single 
command, the type previously associated with any program location. 


Related commands: 


CANCEL TYPE/OVERRIDE 
DEPOSIT 

EXAMINE 
(SET,SSHOW,CANCEL) RADIX 
(SET,SSHOW,CANCEL) MODE 
SHOW TYPE 


1. DBG> SET TYPE ASCII:8 
This command establishes an 8-byte ASCII character string as the default 
type associated with untyped program locations. 

2. DBG> SET TYPE/OVERRIDE LONGWORD 
This command establishes longword integer as the default type associated 
with both untyped program locations and program locations that have 
compiler generated types. 

3. DBG> SET TYPE D FLOAT 
This command establishes D_Floating as the default type associated with 
untyped program locations. 

4, DBG> SET TYPE TYPE=(S_ARRAY) 


This command establishes the type of the variable S_ARRAY as the default 
type associated with untyped program locations. 
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SET VECTOR_MODE 


Enables or disables a debugger vector mode option. 


Applies to vectorized programs. 


Format 
SET VECTOR_MODE vector-mode-option 


Parameters 


vector-mode-option 
Specifies the vector mode option. Valid keywords are as follows: 


SYNCHRONIZED Specifies that the debugger force automatic 
synchronization between the scalar and vector 
processors whenever a vector instruction is executed. 
Specifically, the debugger issues a SYNC instruction 
after every vector instruction and, in addition, an 
MSYNC instruction after any vector instruction that 
accesses memory. This forces the completion of all 
activities associated with the vector instruction that is 
being synchronized: 


e Any exception that was caused by a vector 
instruction is delivered before the next scalar 
instruction is executed. Forcing the delivery 
of a pending exception triggers an exception 
breakpoint or tracepoint (if one was set) or invokes 
an exception handler (if one is available at that 
location in the program). 


e Any read or write operation between vector 
registers and either the general registers or 
memory is completed before the next scalar 
instruction is executed. 


The SET VECTOR_MODE SYNCHRONIZED 
command does not issue an immediate SYNC or 
MSYNC instruction at the time it is issued. Use 
the SYNCHRONIZE VECTOR_MODE command to 
force immediate synchronization. 


NOSYNCHRONIZED Specifies that the debugger not force synchronization 
between the scalar and vector processors except 
for internal debugger purposes. As a result, any 
synchronization is controlled entirely by the program, 
and the program runs as if it were not under debugger 
control. NOSYNCHRONIZED is the default vector 
mode. 
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Description 


Examples 
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Vector mode options control the way in which the debugger interacts with the 
vector processor. See the parameter descriptions for details about the SET 
VECTOR_MODE command. 


Related commands: 


1, 


SHOW VECTOR_MODE 
SYNCHRONIZE VECTOR_MODE 


DBG> SET VECTOR MODE SYNCHRONIZED 


This command causes the debugger to force synchronization between the 
scalar and vector processors after each vector instruction is executed. 


DBG> SHOW VECTOR_MODE 

Vector mode is nonsynchronized 

DBG> SET VECTOR_MODE SYNCHRONIZED @ 
DBG> SHOW VECTOR_MODE 

Vector mode is synchronized 


DBG> STEP 
stepped to .MAIN.\SUB\%LINE 99 
993 VVDIVD V1,V0,V2 


DBG> STEP © 

S$SYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 

break on unhandled exception preceding .MAIN.\SUB\%LINE 100 
100: CLRL RO 

DBG> 


The comments that follow refer to the callouts in the previous example: 


@ The command SET VECTOR_.MODE SYNCHRONIZED causes the 
debugger to force automatic synchronization between the scalar and 
vector processors whenever a vector instruction is executed. 


@ This STEP command suspends program execution on line 99, just before 
a VVDIVD instruction is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 


© This STEP command executes the VVDIVD instruction, which triggers 
the exception. The vector exception is delivered immediately because the 
debugger is being operated in synchronized vector mode. 
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SET WATCH 
Establishes a watchpoint at the location denoted by an address expression. 


Format 


SET WATCH address-expression[, . . . ] [WHEN(conditional-expression)] 
[DO(command[; . . . })] 


Parameters 


address-expression 

Specifies an address expression (a program location) at which a watchpoint is 
to be set. With high-level languages, this is typically the name of a program 
variable and can include a pathname to specify the variable uniquely. More 
generally, an address expression can also be a memory address or a register 
and can be composed of numbers (offsets) and symbols, as well as one or more 
operators, operands, or delimiters. Appendix D identifies the operators that can 
be used in address expressions. 


Do not specify the asterisk (*) wildcard character. 


See Chapter 11 for information that is specific to vector registers. 


conditional-expression 

Specifies a conditional expression in the currently set language that is to be 
evaluated whenever execution reaches the watchpoint. If the expression is 
true, watch action occurs, and the debugger reports that a watchpoint has been 
triggered. If the expression is false, watch action does not occur. In this case, a 
report is not issued, the commands specified by the DO clause are not executed, 
and program execution is continued. 


command 
Specifies a debugger command to be executed as part of the DO clause when 
watch action is taken. 


Qualifiers 


/AFTER:n 

Specifies that watch action not be taken until the nth time the designated 
watchpoint is encountered (n is a decimal integer). Thereafter, the watchpoint 
occurs every time it is encountered provided that conditions in the WHEN clause 
are true. The command SET WATCH/AFTER:1 has the same effect as the SET 
WATCH command. 


/AINTO 

Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions not only within the defining routine, but also within a routine 

that is called from the defining routine (and any other such nested calls). SET 
WATCH/INTO enables you to monitor nonstatic variables within called routines 
more precisely than SET WATCH/OVER; but the speed of execution within called 
routines is faster with SET WATCH/OVER. 
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/OVER 

Specifies that the debugger is to monitor a nonstatic variable by tracing 
instructions only within the defining routine, not within a routine that is called 
by the defining routine. As a result, the debugger executes a called routine at 
normal speed and resumes tracing instructions only when execution returns to 
the defining routine. SET WATCH/OVER provides faster execution than SET 
WATCH/INTO; but if a called routine modifies the watched variable, execution is 
interrupted only upon returning to the defining routine. SET WATCH/OVER is 
the default behavior when you set watchpoints on nonstatic variables. 


/SILENT 

/NOSILENT (default) 

Controls whether the "watch ... " message and the source line for the current 
location are displayed at the watchpoint. The /NOSILENT qualifier specifies that 
the message is displayed. The /SILENT qualifier specifies that the message and 
source line are not displayed. The /SILENT qualifier overrides /SOURCE. 


/SOURCE (default) 

/NOSOURCE 

Controls whether the source line for the current location is displayed at the 
watchpoint. The /SOURCE qualifier specifies that the source line is displayed. 
The /NOSOURCE qualifier specifies that the source line is not displayed. The 
/SILENT qualifier overrides /SOURCE. See also SET STEP [NOJSOURCE. 


/STATIC 

/NOSTATIC 

Enables you to override the debugger’s default determination of whether a 
specified variable (watchpoint location) is static or nonstatic. The /STATIC 
qualifier specifies that the debugger should treat the variable as a static variable, 
even though it might be allocated in Pl space. This causes the debugger to 
monitor the location by using the faster write-protection method rather than by 
tracing every instruction. The /NOSTATIC qualifier specifies that the debugger 
should treat the variable as a nonstatic variable, even though it might be 
allocated in PO space. The /NOSTATIC qualifier causes the debugger to monitor 
the location by tracing every instruction. Exercise caution when using these 
qualifiers. 


‘TEMPORARY 
Causes the watchpoint to disappear after it is triggered (the wexcapo does not 
remain permanently set). 


When an instruction causes the modification of a watchpoint location, the 
debugger takes the following action: 


1. Suspends program execution after that instruction has completed execution. 


2. If/AFTER was specified when the watchpoint was set, checks the AFTER 
count. If the specified number of counts has not been reached, execution 
continues and the debugger does not perform the remaining steps. 


3. Evaluates the expression in a WHEN clause, if one was specified when the 
watchpoint was set. If the value of the expression is false, execution continues 
and the debugger does not perform the remaining steps. 
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4, Reports that execution has reached the watchpoint location, unless /SILENT 
was specified ("watch of... "). 


Reports the old (unmodified) value at the watchpoint location. 
Reports the new (modified) value at the watchpoint location. 


Displays the line of source code at which execution is suspended, unless 
/NOSOURCE or /SILENT was specified when the watchpoint was set, or SET 
STEP NOSOURCE was entered previously. 


8. Executes the commands in a DO clause, if one was specified when the 
watchpoint was set. If the DO clause contains a GO command, execution 
continues and the debugger does not perform the next step. 


9. Issues the prompt. 


For high-level language programs, the address expressions you specify with the 
SET WATCH command are typically variable names. If you specify an absolute 
memory address that is associated with a compiler-generated type, the debugger 
symbolizes the address and uses the length in bytes associated with that type 
to determine the length in bytes of the watchpoint location. If you specify an 
absolute memory address that the debugger cannot associate with a compiler- 
generated type, the debugger watches 4 bytes of memory, by default, beginning 
at the byte identified by the address expression. You can change this length, 
however, by setting the type to either WORD (SET TYPE WORD, which changes 
the default length to 2 bytes) or BYTE (SET TYPE BYTE, which changes the 
default length to 1 byte). SET TYPE LONGWORD restores the default length of 
4 bytes. 


You can set watchpoints on aggregates (that is, entire arrays or records). A 
watchpoint set on an array or record triggers if any element of the array or 
record changes. Thus, you do not need to set watchpoints on individual array 
elements or record components. Note, however, that you cannot set an aggregate 
watchpoint on a variant record. 


You can also set a watchpoint on a record component, on an individual array 
element, or on an array slice (a range of array elements). A watchpoint set on an 
array slice triggers if any element within that slice changes. When setting the 
watchpoint, use the syntax of the current language. 


See Chapter 11 for information that is specific to vector registers. 
The following qualifiers affect what output is seen when a watchpoint is reached: 


/[NOJSILENT 
/[NO]SOURCE 


The following qualifiers affect the timing and duration of watchpoints: 


/AFTER:n 
/TEMPORARY 


The following qualifiers apply only to nonstatic variables: 


INTO 
/OVER 


The following qualifier is used to override the debugger’s determination of 
whether a variable is static or nonstatic: 


/[NO]STATIC 


Debugger Command Dictionary 
SET WATCH 


Static and Nonstatic Watchpoints 

The technique for setting a watchpoint depends on whether the variable is static 
or nonstatic. A static variable is associated with the same memory address 
throughout execution of the program. You can always set a watchpoint on a static 
variable throughout execution. 


A nonstatic variable is allocated on the call stack or in a register and has a value 
only when its defining routine is active (on the call stack). Therefore, you can set 
a watchpoint on a nonstatic variable only when execution is currently suspended 
within the scope of the defining routine (including any routine called by the 
definining routine). The watchpoint is canceled when execution returns from the 
defining routine. 


Another distinction between static and nonstatic watchpoints is speed of 
execution. To watch a static variable, the debugger write-protects the page 
containing the variable. If your program attempts to write to that page, an access 
violation occurs and the debugger handles the exception, determining whether the 
watched variable was modified. Except when writing to that page, the program 
executes at normal speed. 


To watch a nonstatic variable, the debugger traces every instruction in the 
variable’s defining routine and checks the value of the variable after each 
instruction has been executed. Since this significantly slows down execution, 
the debugger issues a message when you set a nonstatic watchpoint. 


As explained in the next paragraphs, the /[NO]JSTATIC and /INTO and /OVER 
qualifiers enable you to exercise some control over speed of execution and other 
factors when watching variables. 


The debugger determines whether a variable is static or nonstatic by checking 
how it is allocated. Typically, a static variable is in PO space (0 to 3FFFFFFF, 
hexadecimal); a nonstatic variable is in Pl space (40000000 to 7FFFFFFF) or 

in a register. The debugger issues a warning if you try to set a watchpoint on 
a variable that is allocated in Pl space or in a register when execution is not 

currently suspended within the scope of the defining routine. 


The /[NOJSTATIC qualifiers enable you to override this default behavior. For 
example, if you have allocated nonstack storage in Pl space, use the /STATIC 
qualifier when setting a watchpoint on a variable that is allocated in that storage 
area. This enables the debugger to use the faster write-protection method of 
watching the location instead of tracing every instruction. Conversely, if, for 
example, you have allocated your own call stack in PO space, use the /NOSTATIC 
qualifier when setting a watchpoint on a variable that is allocated on that 

call stack. This enables the debugger to treat the watchpoint as a nonstatic 
watchpoint. 


You can also control the execution speed for nonstatic watchpoints in called 
routines by means of the /INTO and /OVER qualifiers. 


Global Section Watchpoints 

You can set watchpoints on variables or arbitrary program locations in global 
sections. A global section is a region of memory that is shared among all 
processes of a multiprocess program. A watchpoint that is set on a location in a 
global section (a global section watchpoint) triggers when any process modifies 
the contents of that location. 
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You set a global section watchpoint just as you would set a watchpoint on a static 
variable. However, because of the way the debugger monitors global section 
watchpoints, note the following point. When setting watchpoints on arrays or 
records, performance is improved if you specify individual elements rather than 
the entire structure with the SET WATCH command. 


If you set a watchpoint on a location that is not yet mapped to a global section, 
the watchpoint is treated as a conventional static watchpoint. When the location 
is subsequently mapped to a global section, the watchpoint is automatically 
treated as a global section watchpoint and an informational message is issued. 
The watchpoint is then visible from each process of the multiprocess program. 


Related commands: 


SET BREAK 

SET STEP [NO]JSOURCE 
SET TRACE 
(SHOW,CANCEL) WATCH 


1. DBG> SET WATCH MAXCOUNT 
This command establishes a watchpoint on the variable MAXCOUNT. 


2. DBG> SET WATCH ARR 
DBG> GO 


watch of SUBR\ARR at SUBR\%LINE 12+8 


old value: 
(1): 7 
(2): 12 
(3): 3 
new value: 
(1): : 7 
(2): 12 
(3)3 28 
break at SUBR\SLINE 14 
DBG> 


In this example, the SET WATCH command sets a watchpoint on the 
three-element integer array, ARR. Execution is then resumed with the GO 
command. The watchpoint triggers whenever any array element changes. In 
this case the third element changed. 


3. DBG> SET WATCH ARR(3) 


In this example, the SET WATCH command sets a watchpoint on element 3 
of array ARR (FORTRAN array syntax). The watchpoint triggers whenever 
element 3 changes. 


4, DBG> SET WATCH P_ARR[3:5] 


In this example, the SET WATCH command sets a watchpoint on the array 
slice consisting of elements 3 to 5 of array P_ARR (Pascal array syntax). The 
watchpoint triggers whenever any of these elements change. 
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DBG> SET TRACE/SILENT SUB2 DO (SET WATCH K) 


In this example, variable K is a nonstatic variable and is defined only when 
its defining routine, SUB2, is active (on the call stack). The SET TRACE 
command sets a tracepoint on SUB2. When the tracepoint is triggered during 
execution, the DO clause sets a watchpoint on K. The watchpoint is then 
canceled when execution returns from routine SUB2. The /SILENT qualifier 
on the SET TRACE command suppresses the "trace ... " message and the 
display of source code at the tracepoint. 


DBG 1> SET WATCH ARR(1) 
DBG 1> SHOW WATCH 
watchpoint of PPL3\ARR(1) 
DBG_1> GO 
$DEBUG-I-WATVARNOWGBL, watched variable PPL3\ARR(1) has been remapped 
to a global section 
predefined trace on activation at routine PPL3 in SPROCESS NUMBER 2 
predefined trace on activation at routine PPL3 in %PROCESS NUMBER 3 
watch of PPL3\ARR(1) at PPL3\%LINE 93 in SPROCESS NUMBER 2° 
oss ARR(1) = INDEX 
old value: 0 
new value: 1 
break at PPL3\%LINE 94 in PROCESS NUMBER 2 
94: ARR(I) = 1 
DBG _2> DO (SHOW WATCH) 
For SPROCESS NUMBER 1 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For sPROCESS NUMBER 2 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
For SPROCESS NUMBER 3 
watchpoint of PPL3\ARR(1) [global-section watchpoint] 
DBG 2> 


In this example of a global section watchpoint, the SET WATCH command 
sets a watchpoint on element 1 of array ARR. Because ARR has not yet 


been mapped to a global section, the SHOW WATCH command identifies the 
watchpoint as a conventional static watchpoint. 


After the GO command resumes execution, ARR is remapped to a global 
section. The watchpoint is automatically treated as a global section 
watchpoint. 


Processes 2 and 3 come under debugger control, then the watchpoint is 
triggered in process 2, interrupting execution. At this point, the SHOW 
WATCH command confirms that the watchpoint is visible from each process. 
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SET WINDOW 


Format 


Parameters 


Description 
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Creates a screen window definition. 
SET WINDOW _ window-name AT (start-line,line-count[,start-col,col-count]) 


window-name 
Specifies the name of the window you are defining. If a window definition with 
that name already exists, it is canceled in favor of the new definition. 


start-line 
Specifies the starting line number of the window. This line displays the window 
title, or header line. The top line of the screen is line 1. 


line-count 

Specifies the number of text lines in the window, not counting the header line. 
The value must be at least 1. The sum of start-line and line-count must not 
exceed the current screen height. 


start-col 1 
Specifies the starting column number of the window. This is the column at which 
the first character of the window is displayed. The leftmost column of the screen 
is column 1. 


col-count 

Specifies the number of characters per line in the window. The value must be at 
least 1. The sum of start-col and col-count must not exceed the current screen 
width. 


A screen window is a rectangular region on the terminal screen through which 
you can view a display. The SET WINDOW command establishes a window 
definition by associating a window name with a screen region. You specify the 
screen region in terms of a starting line and height (line count) and, optionally, 

a starting column and width (column count). If you do not specify the starting 
column and column count, they default to column 1 and the current screen width. 


You can specify a window region in terms of expressions that use the built-in 
symbols %PAGE and WIDTH. 


You can use the names of any windows you have defined with the SET WINDOW 
command in a DISPLAY command to position displays on the screen. 


Window definitions are dynamic—that is, window dimensions expand and 
contract proportionally when a SET TERMINAL command changes the screen 
width or height. 


Examples 
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Related commands: 


DISPLAY 

(SET,SSHOW,CANCEL) DISPLAY 
(SET,SSHOW) TERMINAL 
(SHOW,CANCEL) WINDOW 


DBG> SET WINDOW ONELINE AT (1,1) 


This command defines a window named ONELINE at the top of the screen. 
The window is one line deep and, by default, spans the width of the screen. 


DBG> SET WINDOW MIDDLE AT (9,4,30,20) 


This command defines a window named MIDDLE at the middle of the screen. 
The window is 4 lines deep starting at line 9, and 20 columns wide starting 
at column 30. 


DBG> SET WINDOW FLEX AT (%PAGE/4,%PAGE/2, SWIDTH/4, SWIDTH/2) 


This command defines a window named FLEX that occupies a region around 
the middle of the screen and is defined in terms of the current screen height 
(%PAGE) and width (%WIDTH). 
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SHOW ABORT_KEY 


Format 


Description 


Example 
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Identifies the Ctrl-key sequence currently defined to abort the execution of a 
debugger command or to interrupt program execution. 


SHOW ABORT_KEY 


By default, the Ctrl/C sequence, when entered within a debugging session, aborts 
the execution of a debugger command and interrupts program execution. The 
SET ABORT_KEY command enables you to assign the abort function to another 


—Ctri-key sequence. The SHOW ABORT_KEY command identifies the Ctrl-key 


sequence currently in effect for the abort function. 
Related commands: 


Ctrl/C 
SET ABORT_KEY. 


DBG> SHOW ABORT KEY 

Abort Command Key is CTRL C 
DBG> SET ABORT KEY = CTRL P 
DBG> SHOW ABORT KEY 

Abort Command Key is CTRL P 
DBG> 


The first SHOW ABORT_KEY command identifies the default abort command 
key sequence, Ctrl/C. The command SET ABORT_KEY = CTRL_P assigns the 
abort-command function to the Ctrl/P sequence, as verified by the second SHOW 
ABORT_KEY command. 
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SHOW AST 
Indicates whether delivery of ASTs is enabled or disabled. 


Format 
SHOW AST 


Description 


The SHOW AST command indicates whether delivery of ASTs is enabled or 
disabled. The command does not identify an AST whose delivery is pending. The 
delivery of ASTs is enabled by default and with the ENABLE AST command. The 
delivery of ASTs is disabled with the DISABLE AST command. 


Related commands: (ENABLE,DISABLE) AST. 


Example 


DBG> SHOW AST 
ASTs are enabled 
DBG> DISABLE AST 
DBG> SHOW AST 
ASTs are disabled 
DBG> 


The SHOW AST command indicates whether the delivery of ASTs is enabled. 
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SHOW ATSIGN 


SHOW ATSIGN 


Format 


Description 


Related | commands: 


Examples 
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Identifies the default file specification established with the last SET ATSIGN 
command. The debugger uses this file specification when processing the @ 
(Execute Procedure) command. 


SHOW ATSIGN 


@ (Execute Procedure) 
SET ATSIGN 


DBG> SHOW ATSIGN 
No indirect command file default in effect, using DEBUG.COM 
DBG> 


This example shows that, if the SET ATSIGN command was not used, 
command procedures are assumed to have the default file specification 
SYS$DISK:[ ]JDEBUG.COM. 


DBG> SET ATSIGN USER: [JONES.DEBUG] .DBG 

DBG> SHOW ATSIGN 

Indirect command file default is USER: [JONES.DEBUG] .DBG 
DBG> 


In this example, the SHOW ATSIGN command indicates the default file 
specification for command procedures, as previously established with the SET 
ATSIGN command. 
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SHOW BREAK 


Format 


Qualifiers 


Description 


Examples 


Displays information about breakpoints. 
SHOW BREAK 


/PREDEFINED 
Displays information about predefined breakpoints. 


/USER 
Displays information about user defined breakpoints. 


The SHOW BREAK command displays information about breakpoints that are 
currently set, including any options such as WHEN or DO clauses, /AFTER 
counts, and so on. 


By default, SHOW BREAK displays information about both user defined and 
predefined breakpoints (if any). This is equivalent to entering the command 
SHOW BREAK/USER/PREDEFINED. User defined breakpoints are set with the 
SET BREAK command. Predefined breakpoints are set automatically when you 
invoke the debugger, and they depend on the type of program you are debugging. 


See Section 9.3.2 for information about predefined breakpoints that are associated 
with Ada tasking exception events. 


If you established a breakpoint using the /AFTER:n qualifier with the SET 
BREAK command, the SHOW BREAK command displays the current value of 
the decimal integer n, that is, the originally specified integer value minus one for 
each time the breakpoint location was reached. (The debugger decrements n each 
time the breakpoint location is reached until the value of n is zero, at which time 
the debugger takes break action.) | 


Related commands: (SET,CANCEL) BREAK. 


1. DBG> SHOW BREAK 
breakpoint at SUB1\LOOP 
breakpoint at MAIN\MAIN+1F 
do (EX SUB1\D ; EX/SYMBOLIC PSL; GO) 
breakpoint at routine SUB2\SUB2 
/after: 2 
DBG> 


The SHOW BREAK command identifies all breakpoints that are currently 
set. This example indicates user defined breakpoints that are triggered 
whenever execution reaches SUB1\ LOOP, MAIN\ MAIN, and SUB2\ SUB2, 
respectively. 
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2. 


DBG> SHOW BREAK/PREDEFINED 

predefined breakpoint on Ada event "DEPENDENTS EXCEPTION" 
for any value 

predefined breakpoint on Ada event “EXCEPTION TERMINATED" 
for any value 

DBG> 


This command identifies the predefined breakpoints that are currently set. 
The example shows two predefined breakpoints, which are associated with 
Ada tasking exception events. These breakpoints are set automatically by the 
debugger for all Ada programs and for any mixed language program that is 
linked with an Ada module. 
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SHOW CALLS 


Format 


Parameters 


Description 


Identifies the currently active routine calls (the call stack). 


SHOW CALLS _ [integer] 


integer 
A decimal integer that specifies the number of call frames to be identified. By 
default, all currently active call frames are identified. 


Whenever a call is made to a routine as your program executes, the VMS 
operating system creates a separate call frame on the call stack. Each call frame 
stores information about the calling routine. The call frame for the most recently 
called routine is on the top of the call stack. 


When a routine returns execution to its caller, the call frame for that routine is 
removed from the call stack. 


The SHOW CALLS command shows a traceback that lists the sequence of active 
routine calls that lead to the routine in which execution is currently suspended. 
Any recursive routine calls are shown in the display, so you can use the SHOW 
CALLS command to examine the chain of recursion. 


One line of information is displayed for each call frame, starting with the most 
recent call. The top line identifies the currently executing routine, the next line 
identifies its caller, the following line identifies the caller of the caller, and so on. 


The following information is provided for each call frame: 


e The name of the enclosing module. An asterisk (*) to the left of a module 
name indicates that the module is set. 


¢ The name of the calling routine, provided the module is set (the first line 
shows the currently executing routine). 


¢ The line number where the call was made in that routine, provided the 
module is set (the first line shows the line number at which execution is 
suspended). 


¢ The value of the PC in the calling routine at the time that control was 
transferred to the called routine. The PC value is shown as a memory 
address relative to the address of the name of the routine and also as an 
absolute address. 


Even if your program contains no routine calls, the SHOW CALLS command 
displays an active call. The reason for this is that your program has a stack 
frame built for it when it is first activated. Thus, if the SHOW CALLS display 
shows no active calls, either your program has terminated or the call stack has 
been corrupted. 
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Related commands: 


SHOW SCOPE 
SHOW STACK 
Example 

DBG> SHOW CALLS 
module name routine name line rel PC abs PC 
SUB2 SUB2 00000002 0000085A 
*SUB1 SUB1 5 00000014 00000854 
*MAIN MAIN 10 0000002C 0000082C) 
DBG> 


This command displays information about the sequence of currently active 
procedure calls. 
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SHOW DEFINE 


Identifies the default qualifier (ADDRESS, /COMMAND, /PROCESS_GROUP, or 
/VALUE) currently in effect for the DEFINE command. 


Format 
SHOW DEFINE 


Description 
The default qualifier for the DEFINE command is the default qualifier last 


established with the SET DEFINE command. If no SET DEFINE command was 
entered, the default qualifier is /ADDRESS. 


To identify a symbol defined with the DEFINE command, use the SHOW 
SYMBOL/DEFINED command. 


Related commands: 


DEFINE 
DEFINE/PROCESS_GROUP 
DELETE 

SET DEFINE 

SHOW SYMBOL/DEFINED 


Example 


DBG> SHOW DEFINE 
Current setting is: DEFINE/ADDRESS 
DBG> 


The SHOW DEFINE command indicates that the DEFINE command is set for 
definition by address. 
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SHOW DISPLAY 


Format 


Parameters 


Qualifiers 


Description 


CD-212 


Identifies one or more existing screen displays. 


SHOW DISPLAY [display-namef[, .. . J] 


display-name 

Specifies the name of a display. If you do not specify a name, or if you specify the 
asterisk (*) wildcard character by itself, all display definitions are listed. You can 
use * within a display name. Do not specify a display name with /ALL. 


/ALL 


Lists all display definitions. Do not specify a display name with /ALL. 


/SUFFIX[=process-identifier-type] 
Applies to a multiprocess debugging configuration (when DBG$PROCESS has the 
value MULTIPROCESS). Use this qualifier only directly after a display name. 


Appends a process-identifying suffix to a display name. The suffix denotes the 
visible process at the time the command was issued. This qualifier is used 
primarily in command procedures when specifying display definitions or key 
definitions that are bound to display definitions. 


Use any of the following process-identifier-type keywords: 


PROCESS_NAME The display-name suffix is the VMS process name. 


PROCESS_NUMBER _ The display-name suffix is the process number (as shown 
in a SHOW PROCESS display). 


PROCESS_PID The display-name suffix is the VMS process 
identification number (PID). 


If you specify /SUFFIX without a process-identifier-type keyword, the process 
identifier type used for the display-name suffix is, by default, the same as that 
used for the prompt suffix (see SET PROMPT/SUFFIX). 


The SHOW DISPLAY command lists all displays according to their order in the 
display list. The most hidden display is listed first, and the display that is on top 
of the display pasteboard is listed last. 


For each display, the SHOW DISPLAY command lists its name, maximum size, 
screen window, and display kind (including any debug command list). It also 
identifies whether the display is removed from the pasteboard or is dynamic (a 
dynamic display automatically adjusts its window dimensions if the screen size is 
changed with the SET TERMINAL command). 


Example 


Debugger Command Dictionary 
SHOW DISPLAY 


Related commands: 


DISPLAY 
EXTRACT/SCREEN_LAYOUT 
(SET,CANCEL) DISPLAY 
(SET,CANCEL,SHOW) WINDOW 
SHOW SELECT 


DBG> SHOW DISPLAY 
display SRC at Hl, size = 64, dynamic 
kind = SOURCE (EXAMINE/SOURCE  SSOURCE_SCOPE\%PC) 
display INST at Hl, size = 64, removed, dynamic 
kind = INSTRUCTION (EXAMINE/INSTRUCTION .0\%PC) 
display REG at RH1, size = 64, removed, dynamic, kind = REGISTER 
display OUT at S45, size = 100, dynamic, kind = OUTPUT 
display EXSUM at Q3, size = 64, dynamic, kind = DO (EXAMINE SUM) 
display PROMPT at S6, size = 64, dynamic, kind = PROGRAM 
DBG> 


The SHOW DISPLAY command lists all displays currently defined. In this 
example, they include the five predefined displays (SRC, INST, REG, OUT, and 
PROMPT), and the user-defined DO display EXSUM. Displays INST and REG 
are removed from the display pasteboard: the DISPLAY command must be used 
in order to display them on the screen. 
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SHOW EDITOR 


SHOW EDITOR 


Indicates the action taken by the EDIT command, as established by the SET 
EDITOR command. 


Format 
SHOW EDITOR 


Description 
Related commands: 


EDIT 
SET EDITOR 


Examples 


1. DBG> SHOW EDITOR 
The editor is SPAWNed, with command line 
"LSEDIT/START POSITION=(n,1)" 
DBG> a 


This command indicates that, when you enter the EDIT command, you spawn 
the VAX Language-Sensitive Editor in a subprocess. The /START_POSITION 
qualifier that is appended to the command line indicates that the editing 
cursor is initially positioned at the beginning of the line that is centered in 
the debugger’s current source display. . 


2. DBG> SET EDITOR/CALLABLE TPU 
DBG> SHOW EDITOR 
The editor is CALLABLE TPU, with command line "TPU" 
DBG> 


In this example, the SHOW EDITOR command indicates that, when you 
enter the EDIT command, you invoke the callable version of the VAX Text 
Processing Utility (VAXTPU). The editing cursor is initially positioned at the 
beginning of source line 1. | 
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SHOW EVENT_FACILITY 


Format 


Description 


Example 


Identifies the current event facility and the associated event names. 


Event facilities are available for programs that call Ada or SCAN routines or that 
use DECthreads services. 


SHOW EVENT_FACILITY 


The current event facility (ADA, THREADS, or SCAN) defines the eventpoints 
that you can set with the SET BREAK/EVENT and SET TRACE/EVENT 
commands. 


The SHOW EVENT _FACILITY command identifies the event names associated 
with the current event facility. These are the keywords that you can specify 
with the (SET,CANCEL) BREAK/EVENT and (SET,CANCEL) TRACE/EVENT 
commands. 


Related commands: 


(SET,CANCEL) BREAK/EVENT 
SET EVENT_FACILITY 
(SET,CANCEL) TRACE/EVENT 
SHOW BREAK 

SHOW TASK 

SHOW TRACE 


DBG> SHOW EVENT FACILITY 
event facility is THREADS 


This command identifies the current event facility to be THREADS DECthreads 
and lists the associated event names that can be used with a SET BREAK 
/EVENT or SET TRACE/EVENT command. 
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SHOW EXIT_HANDLERS 


SHOW EXIT_HANDLERS 
Identifies the exit handlers that have been declared in your program. 


Format 
SHOW EXIT_HANDLERS 


Description 


The exit handler routines are displayed in the order that they are called (that 
is, last in, first out). The routine name is displayed symbolically, if possible. 
Otherwise, its address is displayed. The debugger’s exit handlers are not 
displayed. 


Example 


DBG> SHOW EXIT HANDLERS 
exit handler at STACKS\CLEANUP 
DBG> 


This command identifies the exit handler routine CLEANUP, which is declared in 
module STACKS. 
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SHOW IMAGE 


SHOW IMAGE 


Format 


Parameters 


Description 


Example 


Displays information about one or more shareable images that are part of your 
running program. 


SHOW IMAGE __[image-name] 


image-name 

Specifies the name of a shareable image to be included in the display. If you do 
not specify a name, or if you specify the asterisk (*) wildcard character by itself, 
all images are listed. You can use * within an image name. 


The SHOW IMAGE command displays the following information: 
¢ Name of the shareable image 
e Start and end addresses of the image 


¢ Whether the image has been set with the SET IMAGE command (loaded into 
the RST) 


* Current image that is your debugging context (marked with an asterisk (* )) 
e¢ Total number of images selected in the display 

¢ Number of bytes allocated for the RST and other internal structures 
Related commands: 


(SET,CANCEL) IMAGE 
(SET,SHOW,CANCEL) MODULE 


DBG> SHOW IMAGE SHARE* 


image name set base address end address 
* SHARE yes 00000200 OOO00FFF 
SHARE1 no 00001000 000017FF 
SHARE2 yes 00018C00 000191FF 
SHARE3 no 00019200 000195FF 
SHARE4 no 00019600 O0OO1B7FF 
total images: 5 bytes allocated: 33032 
DBG> 


This SHOW IMAGE command identifies all of the shareable images whose names 
start with "SHARE" and which are associated with the program. Images SHARE 
and SHARE2 are set. The asterisk (*) identifies SHARE as the current image. 
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SHOW KEY 

SHOW KEY 
Displays the debugger predefined key definitions and those created by the 
DEFINE/KEY command. 

Format 
SHOW KEY _[key-name] 

Parameters 
key-name 
Specifies a function key whose definition is displayed. Do not use the asterisk (* ) 
wildcard character. Instead, use the /ALL qualifier. Do not specify a key name 
with /ALL. Valid key names are as follows: 

Key Name LK201 Keyboard VT100-Type VT52-Type 

PF1 PF1 PFI Blue 

PF2 PF2 PF2 Red 

PF3 PF3 PF3 Black 

PF4 PF4 PF4 

KP0O—KP9 Keypad 0-9 Keypad 0-9 Keypad 0-9 

PERIOD Keypad period (.) Keypad period (.) 

COMMA Keypad comma (, ) Keypad comma (, ) 

MINUS Keypad minus (—) Keypad minus (—) 

ENTER ENTER ENTER ENTER 

E1 Find ; 

E2 Insert Here 

E3 Remove 

B4 Select 

E5 Prev Screen 

E6 Next Screen 

HELP Help 

DO Do 

F6—-F20 F6—F20 

Qualifiers 


/ALL 
Displays all key definitions for the current state, by default, or for the states 
specified with the /STATE qualifier. Do not specify a key name with /ALL. 


/BRIEF 
Displays only the key definitions (by default, all the qualifiers associated with a 
key definition are also shown, including any specified state). 


/DIRECTORY 
Displays the names of all the states for which keys have been defined. Do not 
specify other qualifiers with /DIRECTORY. 
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Description 


Examples 


Debugger Command Dictionary 
SHOW KEY 


/STATE=(state-name [, .. . ]) 

/NOSTATE (default) | 

Selects one or more states for which a key definition is displayed. The /STATE 
qualifier displays key definitions for the specified states. You can specify 
predefined key states, such as DEFAULT and GOLD, or user-defined states. 
A state name can be any appropriate alphanumeric string. The /NOSTATE 
qualifier displays key definitions for the current state only. 


Keypad mode must be enabled (SET MODE KEYPAD) before you can use this 
command. Keypad mode is enabled by default. 


By default, the current key state is the "DEFAULT" state. The current state can 
be changed with the SET KEY/STATE command, or by pressing a key that causes 
a state change (a key that was defined with the DEFINE/KEY/LOCK_STATE 
/STATE qualifier combination). 


Related commands: 


DEFINE/KEY 
DELETE/KEY 
SET KEY 


1. DBG> SHOW KEY/ALL 


This command displays all the key definitions for the current state. 


2. DBG> SHOW KEY/STATE=BLUE KP8 
GOLD keypad definitions: 
KP8 = "Scroll/Top" (noecho, terminate, nolock) 
DBG> 


This command displays the definition for keypad key 8 in the BLUE state. 


3. DBG> SHOW KEY/BRIEF KP8 
DEFAULT keypad definitions: 
KP8 = "Scroll/Up" 
DBG> 


This command displays the definition for keypad key 8 in the current key 
state. 


4. DBG> SHOW KEY/DIRECTORY 
MOVE_GOLD 
MOVE BLUE 
MOVE 
GOLD 
EXPAND _GOLD 
EXPAND BLUE 
EXPAND 
DEFAULT 
CONTRACT_GOLD 
CONTRACT BLUE 
CONTRACT 
BLUE) 

DBG> 


This command displays the names of the states for which keys have been 
defined. 


CD-219 


Debugger Command Dictionary 
SHOW LANGUAGE 


SHOW LANGUAGE 


Identifies the current language. 


Format 
SHOW LANGUAGE 

Description 
The current language is the language last established with the SET LANGUAGE 
command. If no SET LANGUAGE command was entered, the current language 
is, by default, the language of the module containing the main program. 
Related command: SET LANGUAGE. 

Example 


DBG> SHOW LANGUAGE 
language: BASIC 
DBG> 


This command displays the name of the current language as BASIC. 
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SHOW LOG 


Format 


Description 


Examples 


Debugger Command Dictionary 
SHOW LOG 


Indicates whether the debugger is writing to a log file and identifies the current 
log file. 


SHOW LOG 


The current log file is the log file last established by a SET LOG command. 
If no SET LOG command was entered, the current log file is the file 
SYS$DISK:[ ]DEBUG.LOG by default. 


Related commands: 


SET LOG 
SET OUTPUT [NO]JLOG 
SET OUTPUT [NO]JSCREEN_LOG 


DBG> SHOW LOG 
not logging to DEBUG.LOG 
DBG> 


This command displays the name of the current log file as DEBUG.LOG (the 
default log file) and reports that the debugger is not writing to it. 


DBG> SET LOG PROG4 

DBG> SET OUTPUT LOG 

DBG> SHOW LOG 

logging to USERS: [JONES .WORK]PROG4.LOG 
DBG> 


In this example, the SET LOG command establishes that the current log file 
is PROG4.LOG (in the current default directory). The SET OUTPUT LOG 
command causes the debugger to log debugger input and output into that file. 
The SHOW LOG command confirms that the debugger is writing to the log 
file PROG4.COM in the current default directory. 
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SHOW MARGINS 


SHOW MARGINS 


Identifies the current source-line margin settings for the display of source code. 


Format 
SHOW MARGINS 

Description 
The current margin settings are the margin settings last established with the 
SET MARGINS command. If no SET MARGINS command was entered, the left 
margin is set to 1 and the right margin is set to 255 by default. 
Related command: SET MARGINS. 

Examples 


1. DBG> SHOW MARGINS 
left margin: 1 , right margin: 255 
DBG> 


This command displays the default margin settings of 1 and 255. 


2. DBG> SET MARGINS 50 
DBG> SHOW MARGINS 
left margin: 1 , right margin: 50 
DBG> 


This command displays the default left margin setting of 1 and the modified 
right margin setting of 50. 


3. DBG> SET MARGINS 10:60 
DBG> SHOW MARGINS 
left margin: 10 , right margin: 60 
DBG> 


This command displays both margin settings modified to 10 and 60. 
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SHOW MAX_SOURCE_FILES 


SHOW MAX_SOURCE_FILES 


Format 


Description 


Example 


Identifies the maximum number of source files that the debugger can keep open 
at any one time. 


SHOW MAX_SOURCE_FILES 


The maximum number of source files that the debugger can keep open at any one 
time can be specified using the SET MAX _SOURCE_FILES command. If no SET 
MAX SOURCE_FILES command was entered, the maximum number of files is 5 
by default. 


Related commands: 


SET MAX SOURCE_FILES 
(SET,SSHOW,CANCEL) SOURCE 


DBG> SHOW MAX SOURCE FILES 
max_ source files: 7 
DBG> 


This command shows that the debugger can keep a maximum of 7 source files 
open at any one time. 
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SHOW MODE 


Format 


Description 


Example 
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Identifies the current debugger modes (screen or no screen, keypad or nokeypad, 
and so on) and the current radix. 


SHOW MODE 


The current debugger modes are the modes last established with the SET MODE 
command. If no SET MODE command was entered, the current modes are, by 
default: 


DYNAMIC 
NOG_FLOAT (D_fioat) 
INTERRUPT 
KEYPAD 

LINE 

NOSCREEN 

SCROLL 
NOSEPARATE 
SYMBOLIC 


Related commands: 


(SET,CANCEL) MODE 
(SET,SHOW,CANCEL) RADIX 


DBG> SHOW MODE 

modes: symbolic, line, d_float, screen, scroll, keypad, 
dynamic, interrupt, no separate window 

input radix :decimal 

output radix:decimal 

DBG> 


The SHOW MODE command displays the current modes and current input and 
output radix. 
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SHOW MODULE 


Format 


Parameters 


Qualifiers 


Description 


Displays information about the modules in the current image. 


SHOW MODULE = [module-name] 


module-name 

Specifies the name of a module to be included in the display. If you do not specify 
a name, or if you specify the asterisk (*) wildcard character by itself, all modules 
are listed. You can use * within a module name. Shareable image modules are 
selected only if the /SHARE qualifier is specified. 


/RELATED 
/NORELATED (default) 
Applies to Ada programs. 


Controls whether the debugger includes, in the SHOW MODULE display, any 
module that is related to a specified module through a with-clause or subunit 
relationship. 


SHOW MODULE/RELATED displays related modules as well as those specified. 
The display identifies the exact relationship. By default (~NORELATED), no 
related modules are selected for display (only the modules specified are selected). 


/SHARE 

/NOSHARE (default) , 

Controls whether the debugger includes, in the SHOW MODULE display, 
any shareable images that have been linked with your program. By default 
(/(NOSHARE) no shareable image modules are selected for display. 


The debugger creates dummy modules for each shareable image in your program. 
The names of these shareable "image modules" have the prefix "SHARE$". 
SHOW MODULE/SHARE identifies these shareable image modules, as well as 
the modules in the current image. 


Setting a shareable image module loads the universal symbols for that image 
into the run-time symbol table so that you can reference these symbols from the 
current image. However, you cannot reference other (local or global) symbols in 
that image from the current image. This feature overlaps the effect of the newer 
SET IMAGE and SHOW IMAGE commands. 


Note 


The current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 
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Examples 
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The SHOW MODULE command displays the following information about one or 
more modules selected for display: 


Name of the module. 


Programming language in which the module is coded, unless all modules are 
coded in the same language. 


Whether the module has been set with the SET MODULE command. That 
is, whether the symbol records of the module have been loaded into the 
debugger’s run-time symbol table (RST). 


Space (in bytes) required in the RST for symbol records in that module. 
Total number of modules selected in the display. 


Number of bytes allocated for the RST and other internal structures (the 
amount of heap space in use in the main debugger’s process). 


See Section E.1.14.1 for information specific to Ada programs. 


Related commands: 


(SET,SHOW,CANCEL) IMAGE 
SET MODE [NO]DYNAMIC 
(SET,CANCEL) MODULE 
(SET,SHOW,CANCEL) SCOPE 
SHOW SYMBOL 


DBG> SHOW MODULE 


module name symbols size 

TEST yes 432 

SCREEN_IO no 280 

total PASCAL modules: 2. bytes allocated: 2740. 
DBG> 


In this example, the SHOW MODULE command, without a parameter 
specified, displays information about all of the modules in the current image, 
which is the main image by default. This example shows the display format 
when all modules have the same source language. The "symbols" column 
shows that module TEST has been set, but module SCREEN_IO has not. 


DBG> SHOW MODULE FOO, MAIN, SUB* 


module name symbols language size 
FOO yes MACRO 432 
MAIN no FORTRAN 280 
SUB1 no FORTRAN 164 
SUB2 no FORTRAN 204 
total modules: 4. bytes allocated: 60720. 
DBG> 


In this example, the SHOW MODULE command displays information about 
the modules FOO and MAIN, and all modules having the prefix SUB. This 
example shows the display format when the modules do not have the same 
source language. 


Debugger Command Dictionary 


SHOW MODULE 

DBG> SHOW MODULE/SHARE 

module name symbols language size 
FOO yes MACRO 432 
MAIN no FORTRAN 280 
SHARESDEBUG no Image 0 
SHARESLIBRTL no Image 0 
SHARESMTHRTL no Image 0 
SHARE$SHARE1 no Image 0 
SHARE$SHARE2 no Image 0 
total modules: 17. bytes allocated: 162280. 


DBG> SET MODULE SHARES$SHARE2 
DBG> SHOW SYMBOL * IN SHARESSHARE2 
DBG> 


In this example, the SHOW MODULE/SHARE command identifies all 

of the modules in the current image and all of the shareable images 

(the names of the shareable images are prefixed with "SHARE$"). The 
command SET MODULE SHARE$SHARE2 sets the shareable image module 
SHARE$SHARE2. The SHOW SYMBOL command identifies any universal 
symbols defined in the shareable image SHARE2. 
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SHOW OUTPUT 


Format 


Description 


Example 
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Identifies the current output options. 


SHOW OUTPUT 


The current output options are the options last established with the SET 
OUTPUT command. If no SET OUTPUT command was entered, the output 
options are, by default: NOLOG, NOSCREEN_LOG, TERMINAL, NOVERIFY. 


Related commands: 


SET LOG 
SET MODE SCREEN 
SET OUTPUT 


DBG> SHOW OUTPUT 
noverify, terminal, screen_log, 

logging to USERS: [JONES.WORK] DEBUG. LOG; 9 
DBG> 


This command shows the following current output options: 


¢ Debugger commands read from debugger command procedures are not echoed 
on the terminal. 


¢ Debugger output is being displayed on the terminal. 


e The debugging session is being logged to the log file 
USER$:[JONES.WORK]DEBUG.LOG;9. 


e¢ The screen contents are logged as they are updated in screen mode. 
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SHOW PROCESS 


Format 


Parameters 


Qualifiers 


Displays information about processes that are currently under debugger control. 
This command applies especially to a multiprocess debugging configuration (when 
DBG$PROCESS has the value MULTIPROCESS). 


SHOW PROCESS [process-spec[, .. . ]] 


process-spec 
Specifies a process. Use any of the following forms: 


[%PROCESS_NAME] process-name The VMS process name, if that 
name contains no space or lowercase 
characters. The process name can 
include the asterisk (*) wildcard 
character. 


[%PROCESS_NAME] "process-name" The VMS process name, if that name 
contains space or lowercase characters. 
You can also use apostrophes (’ ) instead 
of quotation marks (" ). 

%PROCESS_PID process_id The VMS process identification number 
(PID, a hexadecimal number). 

%PROCESS_NUMBER proc-number The number assigned to a process 

(or %PROC proc-number) when it comes under debugger control. 
Process numbers appear in a SHOW 
PROCESS display. 

process-group-name A symbol defined with the DEFINE 
/PROCESS_GROUP command to 
represent a group of processes. Do not 
specify a recursive symbol definition. 


%NEXT_PROCESS The process after the visible process in 
the debugger’s circular process list. 
%PREVIOUS_PROCESS The process previous to the visible 


process in the debugger’s circular 
process list. 


%VISIBLE_PROCESS The process whose call stack, register 
set, and images are the current context 
for looking up symbols, register values, 
routine calls, breakpoints, and so on. 


You can also use the asterisk (*) wildcard character to specify all processes. If 
you do not specify a process, the visible process is selected, unless you specify 
/ALL. 


/ALL 
Selects all processes known to the debugger for display. Do not specify a process 
with /ALL. 
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Description 


CD-—230 


/BRIEF 
Displays only one line of information for each process selected for display. The 
/BRIEF qualifier is the default. 


/DYNAMIC 

Shows whether dynamic process setting is enabled or disabled. Dynamic process 
setting is enabled by default and is controlled with the command SET PROCESS 
/[NO]DYNAMIC. 


Do not specify a process with /DYNAMIC. Do not specify /ALL, /BRIEF, /FULL, 
/[NOJHOLD, or /VISIBLE with /DYNAMIC. 


/FULL 
Displays maximum information for each process selected for display. 


/HOLD 

/NOHOLD 

Selects either processes that are on hold, or processes that are not on hold for 
display. 


If you do not specify a process, /HOLD selects all processes that are on hold. If . 
you specify a process list, /HOLD selects the processes in the list that are on hold. 


If you do not specify a process, /NOHOLD selects all processes that are not on 
hold. If you specify a process list, /NOHOLD selects the processes in the list that 
are not on hold. 


If you specify both /HOLD and /NOHOLD on the same command line, the effect is 
to select processes that are on hold and processes that are not on hold for display 
(the qualifier specified last on the command line does not override the other). 


/VISIBLE 
Selects the visible process for display. If you do not specify /VISIBLE, it is 
assumed by default. 


The SHOW PROCESS command displays information about specified processes 
and any images running in those processes. 


When used with the /FULL qualifier, the SHOW PROCESS command also 
displays information about the availability and use of the vector processor— 
information that is useful if you are debugging a program that uses vector 
instructions. 


A process can first appear in a SHOW PROCESS display as soon as it comes 
under debugger control. A process can no longer appear in a SHOW PROCESS 
display if it is terminated through an EXIT or QUIT command. 


_ By default (/BRIEF), one line of information is displayed for each process, 


including the following: 


e The process number assigned by the debugger. A process number is assigned 
sequentially, starting with process 1, to each process that comes under 
debugger control. If a process is terminated by an EXIT or QUIT command, 
its process number is not reused during that debugging session. The visible 
process is marked with an asterisk (*) in the leftmost column. 


¢ The VMS process name. 


Debugger Command Dictionary 
SHOW PROCESS 


¢ Whether the process has been put on hold with a SET PROCESS/HOLD 


command. 


¢ The current debugging state for that process (see Table CD-1). 


e The location (symbolized, if possible) at which execution of the image is 
suspended in that process. 


Table CD-1 Debugging States 


State 
Activated 


Break 

Break on branch 

Break on call 

Break on instruction 
Break on lines 

Break on modify of 
Break on return 
Exception break 

Excep. break preceding 


Interrupted . 


Step 
Step on return 


Terminated 


Trace 

Trace on branch 

Trace on call 

Trace on instruction 
Trace on lines 

Trace on modify of 
Trace on return 
Exception trace 

Excep. trace preceding 


Unhandled exception 
Watch of 


Description 


The image and its process have just been brought 
under debugger control, either through a RUN 
/DEBUG command at DCL level, a debugger 
CONNECT command, a Ctrl/YDEBUG sequence, or 
by the program signaling SS$_DEBUG while it was 
not under debugger control. 


A breakpoint was triggered. 


Execution was interrupted in that process, either 
because execution was suspended in another process, 
or because the user interrupted program execution 
with the abort-key sequence (Ctrl/C by default). 


A STEP command has completed. 


The image indicated has terminated execution but 
the process is still under debugger control. Therefore, 
you can obtain information about the image and its 
process. You can use the EXIT or QUIT command to 
terminate the process. 


A tracepoint was triggered. 


An unhandled exception was encountered. 
A watchpoint was triggered. 
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The SHOW PROCESS/FULL gives additional information about processes (see 
the examples). 


Related commands: 


CONNECT 
Ctrl/C 
DEFINE/PROCESS_GROUP 
EXIT 

QUIT 

SET PROCESS 


Examples 


1. DBG 2> SHOW PROCESS 
Number Name 
x 2 WTA3: 
DBG 2> 


The SHOW PROCESS command, by default, displays one line of information 
about the visible process (which is identified with an asterisk (*) in the 
leftmost column. The process has the VMS process name _WTAS3:. It is the 
second process brought under debugger control (process number 2). It is on 
hold, and the image’s execution is suspended at a breakpoint at line 47 of 
module SCREEN. 


Current PC 
SCREEN\SLINE 47 


Hold State 
HOLD break 


2. DBG 2> SHOW PROCESS/FULL SPREVIOUS PROCESS 
Process number: 1 Process name: JONES 1: 
Hold: NO Visible process: NO 
Current PC: TEST VALVES\%LINE 153 
State: interrupted 
PID: 20400885 Owner PID: 00000000 
Current/Base priority: 5/4 Terminal: VTA79: 


Image name: USER$: [JONES.PROG1]TEST VALVES.EXE; 31 
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Elapsed CPU time: 0 00:03:17.17 CPU Limit: Infinite 

Buffered I/O Count: 14894 Remaining buffered I/O quota: 80 
Direct I/O Count: 6956 Remaining direct I/O quota: 40 
Open file count: 7 Remaining open file quota: 43 
Enqueue count: 200 Remaining enqueue quota: 198 
Vector capable: Yes 

Vector consumer: Yes Vector CPU time: 00:00:00.00 


Fast Vector context switches: 0 
Current working set size: 1102 
Current working set extent: 12288 
Peak working set size: 4955 
Current virtual size: 255 
Page faults: 41358 


Active ASTs: 
Event flags: 
DBG_2> 


FF800000 60000003 


The SHOW PROCESS/FULL %PREVIOUS_PROCESS command displays the 


Slow Vector context switches: 0 


Working set size quota: 1304 
Maximum working set extent: 12288 
Maximum authorized working set: 1304 
Peak virtual size: 16182 
Remaining AST Quota: 27 
Event flag wait mask: 7EFEFFFF 


maximum level of information about the previous process in the circular list 
of processes (process number 1, in this case). 


Debugger Command Dictionary 


SHOW PROCESS 
DBG 2> SHOW PROCESS PROCESS NAME TEST 3 
Number Name Hold State Current PC 
7 TEST 3 watch of TEST _3\ROUT4\COUNT 


TEST_3\$LINE 54 
DBG_2> 


This SHOW PROCESS command displays one line of information about 
process TEST_8. The image is suspended at a watchpoint of variable COUNT. 


DBG _2> SHOW PROCESS/DYNAMIC 
Dynamic process setting is enabled 
DBG 2> 


This SHOW PROCESS/DYNAMIC command indicates that dynamic process 
setting is enabled. 
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SHOW RADIX 


SHOW RADIX 


Format 


Qualifiers 


Description 


Examples 
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Identifies the current radix for the entry and display of integer data or, if the 
/OVERRIDE qualifier is specified, the current override radix. 


SHOW RADIX 


/OVERRIDE 
Identifies the current override radix. 


The debugger can interpret and display integer data in any one of four radixes: 
binary, decimal, hexadecimal, and octal. The current radix for the entry and 
display of integer data is the radix last established with the SET RADIX 
command. If no SET RADIX command was entered, the radix for both entry and 
display (input radix and output radix, respectively) is decimal for all languages 
except BLISS and MACRO. It is hexadecimal for BLISS and MACRO. 


The current override radix for the display of all data is the override radix last 
established with the SET RADIX/OVERRIDE command. If no SET RADIX 
/OVERRIDE command was entered, the override radix is "none". 


Related commands: 


DEPOSIT 

EVALUATE 

EXAMINE 
(SET,CANCEL) RADIX 


1. DBG> SHOW RADIX 
input radix: decimal 
output radix: decimal 
DBG> 


This command identifies the input radix and output radix as decimal. 


2. DBG> SET RADIX/OVERRIDE HEX 
DBG> SHOW RADIX/OVERRIDE 
output override radix: hexadecimal 
DBG> 


In this example, the SET RADIX/OVERRIDE command sets the override 
radix to hexadecimal and the SHOW RADIX/OVERRIDE command indicates 


the override radix. This means that all data is displayed as hexadecimal 
integer data in commands such as EXAMINE and so on. 
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SHOW SCOPE 


Format 


Description 


Examples 


Identifies the current scope search list for symbol lookup. 
SHOW SCOPE 


The current scope search list designates one or more program locations (specified 
by pathnames or other special characters) to be used in the interpretation of 
symbols that are specified without pathname prefixes in debugger commands. 


The current scope search list is the scope search list last established with the 
SET SCOPE command. If no SET SCOPE command was entered, the current 
scope search list is 0,1,2, ...,n by default. 


The default scope search list specifies that, for a symbol without a pathname 
prefix, a symbol lookup such as "EXAMINE X" first looks for X in the routine 
that is currently executing (scope 0); if no X is visible there, the debugger looks 
in the caller of that routine (scope 1), and so on down the call stack; if X is not 
found in scope n, the debugger searches the rest of the run-time symbol table 
(RST)—that is, all set modules and the global symbol table (GST), if necessary. 


If you have used a decimal integer in the SET SCOPE command to represent a 
routine in the call stack, the SHOW SCOPE command displays the name of the 
routine represented by the integer, if possible. . 


Related commands: (SET,CANCEL) SCOPE. 


1. DBG> CANCEL SCOPE 
DBG> SHOW SCOPE 


EIGHTQUEENS\TRYCOL\REMOVEQUEEN ], 
EIGHTQUEENS\TRYCOL J], 
EIGHTQUEENS\TRYCOL 1 ] 
EIGHTQUEENS\TRYCOL 2 ] 
EIGHTQUEENS\TRYCOL 3 ] 
EIGHTQUEENS\TRYCOL 4 ] 
EIGHTQUEENS ] 

DBG> SET SCOPE/CURRENT 2 

DBG> SHOW SCOPE 

scope: 


T 
f 
t 
t 


OS ee ee ee ene 
nouou tou ow tt 


EIGHTQUEENS\TRYCOL\REMOVEQUEEN ], 
EIGHTQUEENS\TRYCOL J], 
EIGHTQUEENS\TRYCOL 1 ], 
EIGHTQUEENS\TRYCOL 2 ], 
EIGHTQUEENS\TRYCOL 3 ], 
EIGHTQUEENS\TRYCOL 4 J, 
EIGHTQUEENS ] 


mmm; 
tou uw ew nw ow on 
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SHOW SCOPE 


The CANCEL SCOPE command restores the default scope search list, 

which is displayed by the (first) SHOW SCOPE command. In this example, 
execution is suspended at routine REMOVEQUEEN, after several recursive 
calls to routine TRYCOL. The asterisk (*) indicates that the scope search list 
starts with scope 0, the scope of the routine in which execution is suspended. 


The command SET SCOPE/CURRENT resets the start of the scope search 
list to scope 2. Scope 2 is the scope of the caller of the caller of the routine 
in which execution is suspended. The asterisk in the output of the (second) 
SHOW SCOPE command indicates that the scope search list now starts with 
scope 2. 


DBG> SET SCOPE 0,STACKS\R2,SCREEN I0, \ 
DBG> SHOW SCOPE ~ 
scope: 

0, {= TEST ], 

STACKS\R2, 

SCREEN_I0, 

\ 


DBG> 


In this example, the SET SCOPE command directs the debugger to look for 
symbols without pathname prefixes according to the following scope search 
list. First the debugger looks in the PC scope (denoted by "0", which is in 
module TEST). If the debugger cannot find a specified symbol in the PC scope, 
it then looks in routine R2 of module STACKS; if necessary, it then looks in 
module SCREEN_IO, and then finally in the global symbol table (denoted 

by the global scope, \). The SHOW SCOPE command identifies the current 
scope search list for symbol lookup. No asterisk is shown in the SHOW 
SCOPE display unless the default scope search list is in effect or you have 


previously entered a SET SCOPE/CURRENT command. 
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SHOW SEARCH 


Format 


Description 


Example 


Identifies the default qualifiers /ALL or /NEXT, /IDENTIFIER or /STRING) 
currently in effect for the SEARCH command. 


SHOW SEARCH 


The default qualifiers for the SEARCH command are the default qualifiers last 
established with the SET SEARCH command. If no SET SEARCH command was 
entered, the default qualifiers are (NEXT and /STRING. 


Related commands: 


SEARCH 
(SET,SHOW) LANGUAGE 
SET SEARCH 


DBG> SHOW SEARCH 

search settings: search for next occurrence, as a string 
DBG> SET SEARCH IDENT 

DBG> SHOW SEARCH 

search settings: search for next occurrence, as an identifier 
DBG> SET SEARCH ALL 

DBG> SHOW SEARCH 

search settings: search for all occurrences, as an identifier 
DBG> 


In this example, the firsts SHOW SEARCH command displays the default settings 


for the SET SEARCH command. By default, the debugger searches for and 
displays the next occurrence of the string. 


The second SHOW SEARCH command indicates that the debugger searches for 
the next occurrence of the string, but displays the string only if it is not bounded 
on either side by a character that can be part of an identifier in the current 
language. 


The third SHOW SEARCH command indicates that the debugger searches for all 
occurrences of the string, but displays the strings only if they are not bounded 
on either side by a character that can be part of an identifier in the current 
language. 
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SHOW SELECT 


Format 


Description 


Example 
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Identifies the displays currently selected for each of the display attributes: error, 
input, instruction, output, program, prompt, scroll, and source. 


SHOW SELECT 


The display attributes have the following properties: 


e A display that has the error attribute displays debugger diagnostic 
messages. 


e A display that has the input attribute echoes your debugger input. 


e A display that has the instruction attribute displays the decoded assembly 
language instruction stream of the routine being debugged. The display is 
updated when you enter an EXAMINE/INSTRUCTION command. 


e Adisplay that has the output attribute displays any debugger output that 
is not directed to another display. 


¢ A display that has the program attribute displays program input and 
output. Currently only the PROMPT display can have the program attribute. 


e Adisplay that has the prompt attribute is where the debugger prompts for 
input. Currently, only the PROMPT display can have the PROMPT attribute. 


e A display that has the scroll attribute is the default display for the 
SCROLL, MOVE, and EXPAND commands. 


e A display that has the source attribute displays the source code of the 
module being debugged, if available. The display is updated when you enter 
a TYPE or EXAMINE/SOURCE command. 


Related commands: 


SELECT 
SHOW DISPLAY 


DBG> SHOW SELECT 
display selections: 


scroll = SRC 
input = none 
output = OUT 
error = PROMPT 
source = SRC 


instruction = none 

program = PROMPT 

prompt = PROMPT 
DBG> 


In this example, the SHOW SELECT command identifies the displays currently 
selected for each of the display attributes. The display selections shown are the 
default selections for all languages. 
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SHOW SOURCE 


Format 


Qualifiers 


Description 


Identifies the source directory search lists currently in effect. 


SHOW SOURCE 


/EDIT 
Applies mainly to Ada programs. 


Identifies the search list for source files to be edited when you use the EDIT 
command. 


If a source directory search list has not been established by means of the SET 
SOURCE or SET SOURCE/MODULE=module-name commands, the SHOW 
SOURCE command indicates that no directory search list is currently in effect. 
In this case, the debugger expects each source file to be in the same directory 
that it was in at compile time (the debugger also checks that the version number 
and the creation date and time of a source file match the information in the 
debugger’s symbol table). 


The SET SOURCE/MODULE=module-name command establishes a source 
directory search list for a particular module. The SET SOURCE command 
establishes a source directory search list for all modules not explicitly mentioned 
in a SET SOURCE/MODULE=module-name command. When those commands 
have been used, the SHOW SOURCE command identifies the source directory 
search list associated with each search categories. 


The /EDIT qualifier is needed when the files used for the display of source code 
are different from the files to be edited by means of the EDIT command. This is 
the case with Ada programs. For Ada programs, the SHOW SOURCE command 
identifies the search list of files used for source display (the "copied" source files 
in Ada program libraries); the SHOW SOURCE/EDIT command identifies the 
search list for the source files you edit when using the EDIT command. 


See Section E.1.5 and Section E.1.6 for information specific to Ada programs. 
Related commands: 


(SET,SSHOW) MAX_SOURCE_FILES 
(SET,CANCEL) SOURCE 
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Examples 
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DBG> SHOW SOURCE 
no directory search list in effect 
DBG> SET SOURCE [PROJA], [PROJB],DISK: [PETER.PROJC] 
DBG> SHOW SOURCE 
source directory search list for all modules: 
[PROJA] 
[PROJB] 
DISK: [PETER.PROJC] 
DBG> 


In this example, the SET SOURCE command directs the debugger to search 
the directories [PROJA],[PROJB], and DISK:[PETER.PROJC]. 


DBG> SET SOURCE/MODULE=COBOLTEST [], DISK$2:[PROJD] 
DBG> SHOW SOURCE 
source directory search list for COBOLTEST: 


DISK$2: [PROJD] 
source directory search list for all other modules: 
[PROJA] 
[PROJB] 
DISK: [PETER.PROJC] 
DBG> 


In this example, the SET SOURCE command directs the debugger to search 
the current default directory ([]) and directory DISK$2:[PROJD] for source 
files to use with the module COBOLTEST. 


Debugger Command Dictionary 
SHOW STACK 


SHOW STACK 


Format 


Parameters 


Description 


Example 


Displays information from the current call stack. 


SHOW STACK [integer] 


integer 
Specifies the number of frames to display. If you omit the parameter, the 
debugger displays information about all call stack frames. 


For each call frame, the SHOW STACK command displays information such 

as the condition handler, saved register values, and the argument list, if any. 
The latter is the list of arguments passed to the subroutine with that call. In 
some cases the argument list can contain the addresses of actual arguments. In 
such cases, use the EXAMINE address command to display the values of these 
arguments. 


Related command: SHOW CALLS. 


DBG> SHOW STACK 
stack frame 0 (2146814812) 


condition handler: 0 


SPA: 0 

S: 0 

mask: AM<R2> 

PSW: 0000 (hexadecimal) 
saved AP: 7 
saved FP: 2146814852 
saved PC: EIGHTQUEENS\%LINE 69 
saved R2: 0 


argument list:(1) EIGHTQUEENS\%LINE 68+2 


stack frame 1 (2146814852) 
condition handler: SHARESPASRTL+888 
0 


SPA: 

Ss 0 

mask: none saved 

PSW: 0000 (hexadecimal) 
saved AP: 2146814924 
saved FP: 2146814904 
saved PC: SHARESDEBUG+667 


DBG> 


In this example, the SHOW STACK command displays information about all call 
stack frames at the current PC location. 
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SHOW STEP 


Format 


Description 


Example 
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Identifies the default qualifiers (INTO, /JINSTRUCTION, /NOSILENT and so on) 
currently in effect for the STEP command. 


SHOW STEP 


The default qualifiers for the STEP command are the default qualifiers last 
established by the SET STEP command. If no SET STEP command was entered, 
the default qualifiers are /LINE, /OVER, /NOSILENT, and /SOURCE. 


If you invoke screen mode with the keypad-key sequence PF1-PF3, the SET 
STEP NOSOURCE command is issued in addition to the SET MODE SCREEN 
command (to eliminate redundant source display in output and DO displays). 
In that case, the default qualifiers for the STEP command are /LINE, /OVER, 
/NOSILENT, and /NOSOURCE. 


Related commands: 


STEP 
SET STEP 


DBG> SET STEP INTO, NOSYSTEM, NOSHARE, INSTRUCTION, NOSOURCE 

DBG> SHOW STEP 

step type: nosystem, noshare, nosource, nosilent, into routine calls, 
by instruction 

DBG> 


In this example, the SHOW STEP command indicates that the debugger take the 
following action: 


¢ Steps into called routines, but not those in system space or in shareable 
images . 


¢ Steps by instruction 


¢ Does not display lines of source code while stepping 
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SHOW SYMBOL 


Format 


Parameters 


Qualifiers 


Displays information about the symbols in the debugger’s run-time symbol table 
(RST) for the current image. 


SHOW SYMBOL symbol-namef[, . . . ] [IN scopef, ... ]] 


symbol-name 

Specifies a symbol to be identified. A valid symbol name is a single identifier or a 
label name of the form %LABEL n, where n is an integer. Compound names such 
as RECORD.FIELD or ARRAY[1,2] are not valid. If you specify the asterisk (*) 
wildcard character by itself, all symbols are listed. You can use *. within a symbol 
name. 


scope 
Specifies the name of a module, routine, or lexical block, or a numeric scope. It 
has the same syntax as the scope specification in a SET SCOPE command and 
can include pathname qualification. All specified scopes must be in set modules 
in the current image. 


The SHOW SYMBOL command displays only those symbols in the RST for 

the current image that both match the specified name and are declared within 
the lexical entity specified by the scope parameter. If the scope parameter is 
omitted, all set modules and the global symbol table (GST) for the current image 
are searched for symbols that match the name specified by the symbol-name 
parameter. 


/ADDRESS 

Displays the address specification for each selected symbol. The address 
specification is the method of computing the symbol’s address. It can merely 

be the symbol’s memory address, but it can also involve indirection or an offset 
from a register value. Some symbols have address specifications too complicated 
to present in any understandable way. These address specifications are labeled 
"complex address specifications." 


/DEFINED 
Displays symbols you have defined with the DEFINE command (symbol 
definitions that are in the DEFINE symbol table). 


/DIRECT 

Displays only those symbols that are declared directly in the scope parameter. 
Symbols declared in lexical entities nested within the scope specified by the scope 
parameters are not shown. 


/LOCAL 
Displays symbols that are defined with the DEFINE/LOCAL command (symbol 
definitions that are in the DEFINE symbol table). 


TYPE 
Displays data type information for each selected symbol. 
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SHOW SYMBOL 


Description 


Examples 
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/USE_CLAUSE 
Applies to Ada programs. 


Identifies any Ada package that a specified block, subprogram, or package names 
in a use clause. If the symbol specified is a package, also identifies any block, 
subprogram, package, and so on that names the specified symbol in a use clause. 


Noite 


The current image is either the main image (by default) or the image 
established as the current image by a previous SET IMAGE command. 


The SHOW SYMBOL command displays information that the debugger has about 
a given symbol in the current image. This information might not be the same as 
what the compiler had or even what you see in your source code. Nonetheless, it 
is useful for understanding why the debugger might act as it does when handling 
symbols. 


If you do not specify a qualifier, the SHOW SYMBOL command lists all of the 
possible declarations or definitions of a specified symbol that exist in the RST 
for the current image—that is, in all set modules and in the GST for that image. 
Symbols are displayed with their pathnames. A pathname identifies the search 
scope (module, nested routines, blocks, and so on) that the debugger must follow 
to reach a particular declaration of a symbol. When specifying symbolic address 
expressions in debugger commands, you need to use pathnames only if a symbol 
is defined multiple times and the debugger cannot resolve the ambiguity. 


The /DEFINED and /LOCAL qualifiers display information about symbols 
defined with the DEFINE command (not the symbols that are derived from your 
program). The other qualifiers display information about symbols defined within 
your program. 


See Section E.1.12 and Section E.1.13 for information specific to Ada programs. 
Related commands: 


DEFINE 
DELETE 
SET MODE [NOJLINE 
SET MODE [NO]SYMBOLIC 
| SHOW DEFINE 
SYMBOLIZE 


1. DBG> SHOW SYMBOL I 
data FORARRAY\I 
DBG> 
This command shows that symbol I is defined in module FORARRAY and is a 
variable (data) rather than a routine. 


Debugger Command Dictionary 
SHOW SYMBOL 


DBG> SHOW SYMBOL/ADDRESS INTARRAY1 
data FORARRAY\INTARRAY1 

descriptor address: 0009DE8B 
DBG> 


This command shows that symbol INTARRAY1 is defined in module 
FORARRAY and has a memory address of 00O09DES8B. 


DBG> SHOW SYMBOL *PL* 


This command lists all the symbols whose names contain the string "PL". 


DBG> SHOW SYMBOL/TYPE COLOR 
data SCALARS\MAIN\COLOR 
enumeration type (primary, 3 elements), size: 4 bytes 


This command shows that the variable COLOR is an enumeration type. 


DBG> SHOW SYMBOL/TYPE/ADDRESS * 


This command displays all information about all symbols. 


DBG> SHOW SYMBOL * IN MOD3\COUNTER 
routine MOD3\COUNTER 
data MOD3\COUNTER\X 
data MOD3\COUNTER\Y 

DBG> 


This command lists all the symbols that are defined in the scope denoted by 
the pathname MOD3\ COUNTER. 


DBG> DEFINE/COMMAND SB=SET BREAK 
DBG> SHOW SYMBOL/DEFINED SB 
defined SB 

bound to: SET BREAK 

was defined /command 
DBG> 


In this example, the DEFINE/COMMAND command defines SB as a symbol 
for the command SET BREAK. The SHOW SYMBOL/DEFINED command 
displays that definition. 
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SHOW TASK 


Format 


Parameters 


Qualifiers 
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Displays information about the tasks of a tasking program (also called a 
multithread program). 


SHOW TASK [task-spec[, ... ]] 


task-spec 
Specifies a task value. Use any of the following forms: 


e A task (thread) name as declared in the program, or a language expression 
that yields a task value. You can use a pathname. 


e A task ID (for example, %TASK 2), as indicated in a SHOW TASK display. 
e One of the following task built-in symbols: 


%ACTIVE_TASK The task that runs when a GO, STEP, CALL, or 
EXIT command executes. 
%CALLER_TASK (Applies only to Ada programs.) When an accept 


statement executes, the task that called the entry 
associated with the accept statement. 
%NEXT_TASK The task after the visible task in the debugger’s 
task list. The ordering of tasks is arbitrary but 
consistent within a single run of a program. 
%PREVIOUS_TASK The task previous to the visible task in the 
debugger’s task list. 


%VISIBLE_TASK The task whose call stack and register set are the 
current context for looking up symbols, register 
values, routine calls, breakpoints, and so on. 


Do not use the asterisk (*) wildcard character. Instead, use the /ALL qualifier. 
For details on how to specify tasks with particular qualifiers, see the qualifier 
descriptions. If you do not specify a task or a task selection qualifier (/ALL, 
/INOJHOLD, /PRIORITY, /STATE), the visible task is selected for display. 


/ALL 
Selects all existing tasks for display—namely, tasks that have been created and 
(in the case of Ada tasks) whose master has not yet terminated. 


See the description section for the effect of the current event facility. Do not 
specify a task with /ALL. 


/CALLS[=n] 
Does a SHOW CALLS command for each task selected for display. This identifies 
the currently active routine calls (the call stack) for a task. 


/FULL 

Displays additional information for each task selected for display. The /FULL 
qualifier provides additional information if used either by itself or with the 
/CALLS or /STATISTICS qualifier. 


Description 
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/HOLD 
/NOHOLD 
Selects either tasks that are on hold, or tasks that are not on hold for display. 


If you do not specify a task, /HOLD selects all tasks that are on hold. If you 
specify a task list, /HOLD selects the tasks in the task list that are on hold. 


If you do not specify a task, /NOHOLD selects all tasks that are not on hold. If 
you specify a task list, /NOHOLD selects the tasks in the task list that are not on 
hold. 


See the description section for the effect of the current event facility. 


/PRIORITY=(n[, ... ]) 

If you do not specify a task, selects all tasks having any of the specified priorities, 
n, where n is a decimal integer from 0 to 15. If you specify a task list, selects the 
tasks in the task list that have any of the priorities specified. 


See the Description section for the effect of the current event facility. 


/STATE=(state[, ... ]) 

If you do not specify a task, selects all tasks that are in any of the specified 
states—RUNNING, READY, SUSPENDED, or TERMINATED. If you specify a 
task list, selects the tasks in the task list that are in any of the states specified. 


See the description section for the effect of the current event facility. 


/STATISTICS 

Displays task statistics for the entire tasking system. This information enables 
you to measure the performance of your tasking program. The larger the number 
of total schedulings (also known as context switches), the more tasking overhead 
there is. When you specify /STATISTICS, the only other permissible qualifier is 
/FULL. 


/TIME_SLICE 

Displays the current time-slice value, in seconds, as specified by a previous SET 
TASK/TIME_SLICE command. If no SET TASK/TIME_SLICE command was 
previously entered, displays the time-slice value, if any, that was specified in the 
program. 


If no time-slice value was previously established, the value is 0.0—that is, time 
slicing is disabled. 


Do not specify another qualifier when you specify /TIME_SLICE. 


A task can first appear in a SHOW TASK display as soon as it is created. A task 
can no longer appear in a SHOW TASK display if it is terminated or (in the case 
of an Ada tasking program) if its master is terminated. By default, the SHOW 
TASK command displays one line of information for each task selected. 


Related commands: 


DEPOSIT/TASK 
EXAMINE/TASK 

(SET,SHOW) EVENT_FACILITY 
SET TASK 
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SHOW TASK 


Examples 
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DBG> SHOW EVENT FACILITY 
event facility is ADA 


DBG> SHOW TASK/ALL 


task id pri hold state  substate task object 
* STASK 1 7 RUN 122624 

STASK 2 7 HOLD SUSP Accept H4.MONITOR 

STASK 3 6 READY Entry call H4.CHECK_IN 
DBG> 


In this example, the SHOW EVENT_FACILITY command identifies ADA as 
the current event facility. The SHOW TASK/ALL command provides basic 
information about all the tasks that were created through Ada services and 
currently exist. One line is devoted to each task. The active task is marked 
with an asterisk (*). In this example, it is also the active task (the task that 
is in the RUN state). 

DBG> SHOW TASK SACTIVE _ TASK, sTASK 3, MONITOR 

This command selects the active task, “TASK 3, and task MONITOR for 
display. 

DBG> SHOW TASK/PRIORITY=6 


This command selects all tasks with priority 6 for display. 


DBG> SHOW TASK/STATE= (RUN, SUSP) 

This command selects all tasks that are either running or suspended for 
display. 

DBG> SHOW TASK/STATE=SUSP /NOHOLD 

This command selects all tasks that are both suspended and not on hold for 
display. 

DBG> SHOW TASK/STATE= (RUN, SUSP) /PRIO=7 ‘VISIBLE TASK, sTASK 3 


This command selects for display those tasks among the visible task and 
%TASK 8 that are in either the RUNNING or SUSPENDED STATE and have 
priority 7. 
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SHOW TERMINAL 


Identifies the current terminal screen height (page) and width being used to 
format output. 


Format 
SHOW TERMINAL 


Description 


The current terminal screen height and width are the height and width last 
established by the SET TERMINAL command. If no SET TERMINAL command 
was entered, the current height and width are, by default, the height and 
width known to the VMS terminal driver, as displayed by the DCL command 
SHOW TERMINAL (usually 24 lines and 80 columns, respectively, for VT-series 
terminals). 


Related commands: 


SET TERMINAL 
SHOW DISPLAY 
_ SHOW WINDOW 


Example 


DBG> SHOW TERMINAL 
terminal width: 80 
page: 24 
DBG> 
This command displays the current terminal screen width and height (page) as 
80 columns and 24 lines, respectively. 
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SHOW TRACE 


Format 


Qualifiers 


Description 


Examples 
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Displays information about tracepoints. 


SHOW TRACE 


/PREDEFINED 
Displays information about predefined tracepoints. 


/USER 
Displays information about user defined tracepoints. 


The SHOW TRACE command displays information about tracepoints that are 
currently set, including any options such as WHEN or DO clauses, /AFTER 
counts, and so on. 


By default, SHOW TRACE displays information about both user defined and 
predefined tracepoints (if any). This is equivalent to entering the command 
SHOW TRACE/USER/PREDEFINED. User defined tracepoints are set with the 
SET TRACE command. Predefined tracepoints are set automatically when you 
invoke the debugger, and they depend on the type of program you are debugging. 
See Chapter 10 for information about predefined tracepoints that are associated 
with multiprocess programs. 


If you established a tracepoint using the /AFTER:n qualifier with the SET TRACE 
command, the SHOW TRACE command displays the current value of the decimal 
integer n, that is, the originally specified integer value minus one for each time 
the tracepoint location was reached. (The debugger decrements n each time 

the tracepoint location is reached until the value of n is zero, at which time the 
debugger takes trace action.) 


Related commands: (SET,CANCEL) TRACE. 


1. DBG> SHOW TRACE 
tracepoint at routine CALC\MULT 
tracepoint on calls: 
RET RSB BSBB JSB BSBW CALLG CALLS 
DBG> 


The SHOW TRACE command identifies all tracepoints that are currently set. 
This example indicates user defined tracepoints that are triggered whenever 
execution reaches routine MULT in module CALC or one of the instructions 
RET, RSB, BSBB, JSB, BSBW, CALLG, or CALLS. 


Debugger Command Dictionary 
SHOW TRACE 


DBG 2> SHOW TRACE/PREDEFINED 
predefined tracepoint on program activation 
DO (SET DISP/DYN/REM/SIZE:64/PROC SRC_/SUF=PROCESS NU AT H1 SOURCE 
(EXAM/SOURCE .%SOURCE_SCOPE\%PC) ; 
SET DISP/DYN/REM/SIZE:64/PROC INST _/SUF=PROCESS NU AT H1 INST 

(EXAM/INSTRUCTION .0\%PC) ) 

predefined tracepoint on program termination 

DBG 2> 


This command identifies the predefined tracepoints that are currently set. 
The example shows the predefined tracepoints that are set automatically 
by the debugger for a multiprocess program (when DBG$PROCESS has 

the value MULTIPROCESS). The tracepoint on program activation triggers 
whenever a new process comes under debugger control. The DO clause 
creates a process-specific source display named SRC_n and a process-specific 
instruction display named INST_n whenever a process activation tracepoint 
is triggered. The tracepoint on program termination triggers whenever a 
process does an image exit. 
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SHOW TYPE 


Format 


Identifies the current type for program locations that do not have a compiler- 
generated type or, if the /OVERRIDE qualifier is specified, the current override 


type. 


SHOW TYPE 


Qualifiers 


Description 


Examples 
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/OVERRIDE 
Identifies the current override type. 


The current type for program locations that do not have a compiler-generated 
type is the type last established by the SET TYPE command. If no SET TYPE 
command was entered, the type for those locations is longword integer. 


The current override type for all program locations is the override type 
last established by the SET TYPE/OVERRIDE command. If no SET TYPE 
/OVERRIDE command was entered, the override type is "none". 


Related commands: 


CANCEL TYPE/OVERRIDE 
DEPOSIT 

EXAMINE 
(SET,SHOW,CANCEL) MODE 
(SET,SHOW,CANCEL) RADIX 
SET TYPE 


1. DBG> SET TYPE QUADWORD 
DBG> SHOW TYPE 
type: quadword integer 
DBG> 


This command sets the type for locations that do not have a compiler 
generated type to quadword. The SHOW TYPE command displays the 
current default type for those locations as quadword integer. This means that 
the debugger interprets and displays entities at those locations as quadword 
integers unless you specify otherwise (for example with a type qualifier on the 
EXAMINE command). 


2. DBG> SHOW TYPE/OVERRIDE 
type/override: none 
DBG> 


This command indicates that no override type has been defined. 
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SHOW VECTOR_MODE 


Format 


Description 


Example 


Identifies the current vector mode (synchronized or nonsynchronized). 


Applies to vectorized programs. 


SHOW VECTOR_MODE 


The current vector mode is the mode established with the SET VECTOR_MODE 
command. If no SET VECTOR_MODE command was entered, the vector mode is, 
by default, nonsynchronized. 


Related commands: 


SET VECTOR_MODE [NO]JSYNCHRONIZED 
SYNCHRONIZE VECTOR_MODE 


DBG> SHOW VECTOR MODE 

Vector mode is nonsynchronized 
DBG> SET VECTOR _MODE SYNCHRONIZED 
DBG> SHOW VECTOR MODE 

Vector mode is synchronized 

DBG> 


The SHOW VECTOR_MODE command indicates the effect of the SET VECTOR. 
MODE command. 
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SHOW WATCH 


Format 


Description 


Example 
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Displays information about watchpoints. 


SHOW WATCH 


The SHOW WATCH command displays information about watchpoints that are 
currently set, including any options such as WHEN or DO clauses, /AFTER 
counts, and so on. 


If you established a watchpoint using the /AFTER:n qualifier with the SET 
WATCH command, the SHOW WATCH command displays the current value of 
the decimal integer n, that is, the originally specified integer value minus one for 
each time the watchpoint location was reached. (The debugger decrements n each 
time the watchpoint location is reached until the value of n is zero, at which time 
the debugger takes watch action.) 


Related commands: (SET,CANCEL) WATCH. 


DBG> SHOW WATCH 

watchpoint of MAIN\X 
watchpoint of SUB2\TABLE+20 
DBG> 


This command displays two watchpoints, one at the variable X (defined in module 
MAIN), and the other at the location SUB2\ TABLE+20 (20 bytes beyond the 
address denoted by the address expression TABLE). 
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SHOW WINDOW 


Format 


Parameters 


Qualifiers 


Description 


Example 


Identifies the name and screen position of predefined and user-defined 
screen-mode windows. 


SHOW WINDOW §[window-namef[, .. . ]] 


windowname 

Specifies the name of a screen window definition. If you do not specify a name, or 
if you specify the asterisk (*) wildcard character by itself, all window definitions 
are listed. You can use * within a window name. Do not specify a window 
definition name with /ALL. 


/ALL 
Lists all window definitions. Do not specify a window definition name with /ALL. 


Related commands: 


(SET,SHOW,CANCEL) DISPLAY 
(SET,SSHOW) TERMINAL 
(SET,CANCEL) WINDOW 
SHOW SELECT 


DBG> SHOW WINDOW LH*,RH* 
window LH1 at (1,11,1,40) 
window LH12 at (1,23,1,40) 
window LH2 at (13,11,1,40) 
window RH1 at (1,11, 42,39) 
window RH12 at (1,23,42,39) 
window RH2 at (13,11, 42,39) 
DBG> 


This command displays the name and screen position of all screen window 
definitions whose names starts with LH or RH. 
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SPAWN 


SPAWN 


Format 


Parameters 


Qualifiers 
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Creates a subprocess, enabling you to execute DCL commands without 
terminating a debugging session or losing your debugging context. 


SPAWN = [DCL-command] 


DCL-command 

Specifies a DCL command. If you specify a DCL command, the command is 
executed in a subprocess. Control is returned to the debugging session when the 
DCL command terminates. 


If you do not specify a DCL command, a subprocess is created and you can then 
enter DCL commands. Either logging out of the spawned process or attaching to 
the parent process (with the DCL command ATTACH) enables you to continue 
your debugging session. 


If the DCL command contains a semicolon, you must enclose the command in 
quotation marks ("). Otherwise the semicolon is interpreted as a debugger 
command separator. To include a quotation mark inside the string, enter two 
consecutive quotation marks (""). 


/INPUT=file-spec 

Specifies an input DCL command file containing one or more DCL commands 

to be executed by the spawned subprocess. The default file type is .COM. If you 
specify a DCL command string with the SPAWN command and an input file with 
the /INPUT qualifier, the command string is processed before the input file. After 
processing of the input file is complete, the subprocess is terminated. Do not use 
the asterisk (*) wildcard character in the file specification. 


/OUTPUT=file-spec 

Writes the output from the SPAWN operation to the specified file. The default 
file type is .LOG. Do not use the asterisk (*) wildcard character in the file 
specification. 


/WAIT (default) 

/NOWAIT 

Controls whether the debugging session (the parent process) is suspended while 
the subprocess is running. The /WAIT qualifier (default) suspends the debugging 
session until the subprocess is terminated. You cannot enter debugger commands 
until control returns to the parent process. 


The /NOWAIT qualifier executes the subprocess in parallel with the debugging 
session. You can enter debugger commands while the subprocess is running. 

If you use /NOWAIT, you should specify a DCL command with the SPAWN 
command; the DCL command is executed in the subprocess. A message indicates 
when the spawned subprocess completes. 


Description 


Examples 
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The SPAWN command acts exactly like the DCL command SPAWN. You can edit 
files, compile programs, read mail, and so on without ending your debugging 
session or losing your current debugging context. 


In addition, you can spawn a DCL command SPAWN. DCL processes the second 
SPAWN command, including any qualifier specified with that command. 


Related command: ATTACH. 


1. DBG> SPAWN 
$ 


This command shows that the SPAWN command, with no parameter specified, 
creates a subprocess at DCL level. You can now enter DCL commands. Log 
out to return to the debugger prompt. 


2. DBG> SPAWN/NOWAIT/INPUT=READ NOTES/OUTPUT=0428NOTES 
DBG> 


This command creates a subprocess that is executed in parallel with the 
debugging session. This subprocess executes the DCL command procedure 
READ_NOTES.COM. The output from the spawned operation is written to 
the file 0428NOTES.LOG. 


3. DBG> SPAWN/NOWAIT SPAWN/OUT=MYCOM.LOG @MYCOM 
DBG> 


This command creates a subprocess that is executed in parallel with the 
debugging session. This subprocess creates another subprocess to execute the 
DCL command procedure MYCOM.COM. The output from that operation is 
written to the file MYCOM.LOG. 
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STEP 


STEP 


Format 


Parameters 


Qualifiers 
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Executes the program up to the next line, instruction, or other specified location. 
STEP [integer] 


intger 

A decimal integer that specifies the number of step units (lines, instructions, and 
so on) to be executed. If you omit the parameter, the debugger executes one step 
unit. 


/BRANCH 
Executes the program to the next branch instruction. STEP/BRANCH has the 
same effect as SET BREAK/TEMPORARY/BRANCH;GO. 


/CALL 
Executes the program to the next call or RET instruction. STEP/CALL has the 
same effect as SET BREAK/TEMPORARY/CALL;GO. 


/EXCEPTION 

Executes the program to the next exception, if any. STEP/EXCEPTION has 
the same effect as SET BREAK/TEMPORARY/EXCEPTION;GO. If no exception 
occurs, STEP/EXCEPTION has the same effect as GO. 


/AINSTRUCTION[=(opcodef, .. . ])] 

If you do not specify an opcode, executes the program to the next instruction. 
STEP/INSTRUCTION has the same effect as SET BREAK/TEMPORARY 
/JINSTRUCTION;GO. 


If you specify one or more opcodes, executes the program to the next instruction 
whose opcode is specified in the list. STEP/AINSTRUCTION=(opcode[, .. . ]) 

has the same effect as SET BREAK/TEMPORARY/INSTRUCTION= 

(opcode[, .. . ]);GO. 


If you specify a vector instruction, do not include an instruction qualifier (/U, /V, 
/M, /0, or /1) with the instruction mnemonic. 


/INTO 

If execution is currently suspended at a routine call, STEP/INTO executes the 
program up to the beginning of that routine (steps into that routine). Otherwise, 
STEP/INTO has the same effect as STEP without a qualifier. The /INTO qualifier 
is the opposite of /OVER (the default behavior). 


The STEP/INTO behavior can be changed by also using the /[NO]JSB, 
/INOJSHARE, and /[NO]JSYSTEM qualifiers. 


/JSB 

/NOJSB 

Qualifies a previous SET STEP INTO command or a current STEP/INTO 
command. 
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If execution is currently suspended at a routine call and the routine is called 
by a JSB instruction, STEP/INTO/NOJSB has the same effect as STEP/OVER. 
Otherwise, STEP/INTO/NOJSB has the same effect as STEP/INTO. 


Use STEP/INTO/JSB to override a previous SET STEP NOJSB command. 
STEP/INTO/JSB enables a STEP/INTO command to step into routines that are 
called by a JSB instruction, as well as into routines that are called by a CALL 
instruction. 


The /JSB qualifier is the default for all languages except DIBOL. The /NOJSB 

qualifier is the default for DIBOL. In DIBOL, application-declared routines are 
called by the CALL instruction and DIBOL run-time library routines are called 
by the JSB instruction. 


/LINE 

Executes the program to the next line of source code. However, the debugger 
skips over any source lines that do not result in executable code when compiled 
(for example, comment lines). STEP/LINE has the same effect as SET BREAK 
/TEMPORARY/LINE;GO. This is the default behavior for all languages. 


/OVER 

If execution is currently suspended at a routine call, STEP/OVER executes 
the routine up to and including the routine’s RET instruction (steps over that 
routine). The /OVER qualifier is the default behavior and is the opposite of 
ANTO. 


/RETURN 

Executes the routine in which execution is currently suspended up to its RET 
instruction (that is, up to the point just prior to transferring control back to the 
calling routine). This enables you to inspect the local environment (for example, 
obtain the values of local variables) before the RET instruction deletes the 
routine’s call frame from the call stack. STEP/RETURN has the same effect as 
SET BREAK/TEMPORARY/RETURN;GO. 


STEP/RETURN n executes the program up n levels of the call stack. 


/SHARE (default) 

/NOSHARE 

Qualifies a previous SET STEP INTO command or a current STEP/INTO 
command. 


If execution is currently suspended at a call to a shareable image routine, STEP 
/INTO/NOSHARE has the same effect as STEP/OVER. Otherwise, STEP/INTO 
/NOSHARE has the same effect as STEP/INTO. 


Use STEP/INTO/SHARE to override a previous SET STEP NOSHARE command. 
STEP/INTO/SHARE enables a STEP/INTO command to step into shareable 
image routines, as well as into other kinds of routines. 


/SILENT 

/NOSILENT (default) 

Controls whether the "stepped to ... " message and the source line for the 
current location are displayed after the STEP has completed. The /NOSILENT 
qualifier specifies that the message is displayed. The /SILENT qualifier specifies 
that the message and source line are not displayed. The /SILENT qualifier 
overrides /SOURCE. 
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STEP 


Description 
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/SOURCE (default) 

/NOSOURCE 

Controls whether the source line for the current location is displayed after the 
STEP has completed. The /SOURCE qualifier specifies that the source line 

is displayed. The /NOSOURCE qualifier specifies that the source line is not 
displayed. The /SILENT qualifier overrides /SOURCE. See also SET STEP 
[NO]SOURCE. 


/SYSTEM (default) 

/NOSYSTEM 

/[NO]SYSTEM qualifies a previous SET STEP INTO command or a current 
STEP/AINTO command. 


If execution is currently suspended at a call to a system routine (in P1 space), 
STEP/INTO/NOSYSTEM has the same effect as STEP/OVER. Otherwise, STEP 
/AINTO/NOSYSTEM has the same effect as STEP/INTO. 


Use STEP/INTO/SYSTEM to override a previous SET STEP NOSYSTEM 
command. STEP/INTO/SYSTEM enables a STEP/INTO command to step into 
system routines, as well as into other kinds of routines. 


/VECTOR_INSTRUCTION 

Executes the program to the next vector instruction. STEP/VECTOR_ 
INSTRUCTION has the same effect as SET BREAK/TEMPORARY/VECTOR_ 
INSTRUCTION;GO. 


The STEP command is one of the four debugger commands that can be used to 
execute your program (the others are CALL, EXIT, and GO). 


The behavior of the STEP command depends on the following factors: 


¢ The default STEP mode previously established with a SET STEP command, if 
any 


¢ The qualifier specified with the STEP command, if any 
e The number of step units specified as parameter to the STEP command, if 
any 


If no SET STEP command was previously entered, the debugger takes the 
following default action when you enter a STEP command without specifying a 
qualifier or parameter: 


1. Executes a line of source code (STEP/LINE is the default). 


2. Reports that execution has completed by issuing a "stepped to ... " message 
(STEP/NOSILENT is the default). 


3. Displays the line of source code at which execution is suspended (STEP 
/SOURCE is the default). 


4. Issues the prompt. 
The following STEP command qualifiers affect the location to which you step: 


/BRANCH 

/CALL 

/EXCEPTION 
ANSTRUCTION[=(opcode[, ... ])] 
/LINE 
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/RETURN 
/VECTOR_INSTRUCTION 


The following qualifiers affect what output is seen upon completion of a step: 


/[NO]JSILENT 
/[NO]JSOURCE 


The following qualifiers affect what happens at a routine call: 


AINTO 
/[NO]JSB 
/OVER 
/[NO]SHARE 
/[NO]ISYSTEM 


If you plan to enter several STEP commands with the same qualifiers, you 

can first use the SET STEP command to establish new default qualifiers (for 
example, SET STEP INTO NOSYSTEM makes the STEP command behave like 
STEP/INTO/NOSYSTEM). Then you do not have to use those qualifiers with the 
STEP command. You can override the current default qualifiers for the duration 
of a single STEP command by specifying other qualifiers. Use the SHOW STEP 
command to identify the current STEP defaults. 


If an exception breakpoint is triggered (resulting from a SET BREAK 
/EXCEPTION or a STEP/EXCEPTION command), execution is suspended 
before any application-declared condition handler is invoked. If you then resume 
execution with the STEP command, the debugger resignals the exception and the 
program executes to the beginning of (steps into) the condition handler, if any. 


If you are using the multiprocess debugging configuration to debug a multiprocess 
program (if the logical name DBG$PROCESS has the value MULTIPROCESS), 
note the following additional points: 


¢ The STEP command is executed in the context of the visible process, but 
images in any other processes that are not on hold (through a SET PROCESS 
/HOLD command) are also allowed to execute. If you use the DO command 
to broadcast a STEP command to one or more processes, the STEP command 
is executed in the context of each specified process that is not on hold, but 
images in any other processes that are not on hold are also allowed to execute. 
In all cases, a hold condition in the visible process is ignored. 


e After execution is started, the way in which it continues depends on whether 
the SET MODE [NOJINTERRUPT command was entered. By default (SET 
MODE INTERRUPT), execution continues until it is suspended in any 
process. At that point, execution is interrupted in any other processes that 
were executing images, and the debugger prompts for input. 


Related commands: 


CALL 

DO 

EXIT 

GO 

SET BREAK/EXCEPTION 
SET MODE [NO]JINTERRUPT 
SET PROCESS 

(SET,SSHOW) STEP 
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DBG> SHOW STEP 
step type: source, nosilent, by line, 
over routine calls 
DBG> STEP 
stepped to SQUARESSMAIN\%LINE 4 
4; OPEN (UNIT=8, FILE='’DATAFILE.DAT’, STATUS=’OLD’ ) 
DBG> 


The SHOW STEP command identifies the default qualifiers currently in 
effect for the STEP command. In this case, the STEP command, without 
any parameters or qualifiers, causes the debugger to execute the next line of 
source code. After the STEP command has completed, execution is suspended 
at the beginning of line 4. 


DBG> STEP 5 

stepped to MAIN\%LINE 47 
47: SWAP (X,Y); 
DBG> 


This command causes the debugger to execute the next 5 lines of source 
code. After the STEP command has completed, execution is suspended at the 
beginning of line 47. 


DBG> STEP/INTO 
stepped to routine SWAP 
23: procedure SWAP (A,B: in out integer) is 
DBG> STEP 
stepped to MAIN\SWAP\SLINE 24 
: TEMP: integer := 0; 
DBG> STEP/RETURN 
stepped on return from MAIN\SWAP\SLINE 24 to MAIN\SWAP\%LINE 29 
29: end SWAP; 
DBG> 


In this example, the STEP/INTO command causes the debugger to execute the 
program up to the beginning of the routine that is being called at the current 
PC value (routine SWAP, in this case). The STEP command executes the next 
line of source code. The STEP/RETURN command causes the debugger to 
finish executing routine SWAP up to its RET instruction (that is, up to the 
point just prior to transferring control back to the calling routine). 


DBG> SET STEP INSTRUCTION 

DBG> SHOW STEP 

step type: source, nosilent, by instruction, 

over routine calls 

DBG> STEP 

stepped to SUBI\%LINE 26: MOVL S*#4,B*-20 (FP) 
26: Z:integer:=4; 

DBG> 


In this example, the SET STEP INSTRUCTION command establishes the 
default STEP command qualifier to be INSTRUCTION. This is verified by the 
SHOW STEP command. The STEP command causes the debugger to execute 


the next instruction. After the STEP command has completed, execution is 
suspended at the first instruction (MOVL) of line 26 in module SUBI1. 
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SYMBOLIZE 
Converts a memory address to a symbolic representation, if possible. 


Format 
SYMBOLIZE address-expression[, .. . ] 


Parameters 


address-expression 
Specifies an address expression to be symbolized. Do not use the asterisk (*) 
wildcard character. 


Description 


If the address is a static address, it is symbolized as the nearest preceding 
symbol name, plus an offset. If the address is also a code address and a line 
number can be found that covers the address, the line number is included in the 
symbolization. 


If the address is a register address, the debugger displays all symbols in all set 
modules that are bound to that register. The full pathname of each such symbol 
is displayed. The register name itself ("%R5", for example) is also displayed. 


If the address is a call stack location in the call frame of a routine in a set 
module, the debugger searches for all symbols in that routine whose addresses 
are relative to the Frame Pointer (FP) or the Stack Pointer (SP). The closest 
preceding symbol name plus an offset is displayed as the symbolization of the 
address. A symbol whose address specification is too complex is ignored. 


If the debugger can find no symbolization for the address, a message is displayed. 
Related commands: 


EVALUATE/ADDRESS 

SET MODE [NO]LINE 

SET MODE [NO]SYMBOLIC 
(SET,SHOW,CANCEL) MODULE 
SHOW SYMBOL 


Examples 


1. DBG> SYMBOLIZE %R5 
address PROG\$R5: 
PROG\X 
DBG> 


This example shows that the local variable X in routine PROG is located in 
register R5. 


2. DBG> SYMBOLIZE %HEX 27C9E3 
address 0027C9E3: 
MOD5\X 
DBG> 


This command directs the debugger to treat the integer literal 27C9E3 as a 
hexadecimal value and convert that address to a symbolic representation, if — 
possible. The address converts to the symbol X in module MODS. 
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SYNCHRONIZE VECTOR_MODE 


Format 


Description 


Examples 
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Forces immediate synchronization between the scalar and vector processors. 


Applies to vectorized programs. 


SYNCHRONIZE VECTOR_MODE 


The command SYNCHRONIZE VECTOR_MODE forces immediate 
synchronization between the scalar and vector processors by issuing a SYNC 
and an MSYNC instruction. The effect is as follows: 


e Any exception that was caused by a vector instruction and was still pending 
delivery is immediately delivered. Forcing the delivery of a pending exception 
triggers an exception breakpoint or tracepoint (if one was set) or invokes an 
exception handler (if one is available at that location in the program). 


e Any read or write operation between vector registers and either the general 
registers or memory is completed immediately—that is, any vector memory 
instruction that was still being executed completes execution. 


Entering the SYNCHRONIZE VECTOR_MODE command is equivalent to issuing 
SYNC and MSYNC instructions at the location in the program at which execution 
is suspended. 


By default, the debugger does not force synchronization between the scalar 
and vector processors during program execution (SET VECTOR_MODE 
NOSYNCHRONIZED). Use the SET VECTOR_MODE SYNCHRONIZED 
command to force such synchronization. 


Related commands: 


SET VECTOR_MODE [NO]SYNCHRONIZED 
SHOW VECTOR_MODE 


1. DBG> SYNCHRONIZE VECTOR MODE 
SDEBUG-I-SYNCREPCOM, Synchronize reporting complete 
DBG> 


The SYNCHRONIZE VECTOR_MODE command forces immediate 
synchronization between the scalar and vector processors. In this example, 
the diagnostic message indicates that the synchronization operation has 
completed and that all pending vector exceptions have been delivered and 
reported. 
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DBG> STEP @ 

stepped to .MAIN.\SUB\%LINE 99 
99: VVDIVD v1,V0,V2 

DBG> STEP @Q@ 

stepped to .MAIN.\SUB\%LINE 100 


100: CLRL RO 
DBG> EXAMINE/FLOAT $v2 ®@© 
O\%V2 
[0]: 13.53400 
[1]: Reserved operand, encoded as floating divide by zero 


[2]: 247.2450 


DBG> SYNCHRONIZE VECTOR MODE @ 
SSYSTEM-F-VARITH, vector arithmetic fault, summary=00000002, 
mask=00000004, PC=000002E1, PSL=03C00010 
break on unhandled exception preceding .MAIN.\SUB\SLINE 100 
100: CLRL RO) 
DBG> 


The comments that follow refer to the callouts in the previous example: 


@ This STEP command suspends program execution on line 99, just before 
a VVDIVD instruction is executed. Assume that, in this example, the 
instruction will trigger a floating-point divide-by-zero exception. 


@ This STEP command executes the VVDIVD instruction. Note, however, 
that the exception is not delivered at this point in the execution of the 
program. 

© The EXAMINE/FLOAT command displays a decoded exception message 
in element 1 of the destination register, V2. This confirms that a floating- 
point divide-by-zero exception was triggered and is pending delivery. 


@ The SYNCHRONIZE VECTOR_MODE command forces the immediate 
delivery of the pending vector exception. 
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TYPE 


Format 


Parameters 


Description 
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Displays lines of source code. 


TYPE [[module-name\]line-numf[:line-num] 
[,[module-name\]line-num[:line-num][, .. . ]] 


module-name 

Specifies the module that contains the source lines to be displayed. If you specify 
a module name along with the line numbers, use standard pathname notation: 
insert a backslash ( \ ) between the module name and the line numbers. 


If you do not specify a module name, the debugger uses the current scope (as 
established by a previous SET SCOPE command, or the PC scope if no SET 
SCOPE command was entered) to find source lines for display. If you specify 
a scope search list with the SET SCOPE command, the debugger searches for 
source lines only in the module associated with the first named scope. 


line-num 
Specifies a compiler-generated line number (a number used to label a source 
language statement or statements). 


If you specify a single line number, the debugger displays the source code 


corresponding to that line number. 


If you specify a list of line numbers, separating each with a comma, the debugger 
displays the source code corresponding to each of the line numbers. 


If you specify a range of line numbers, separating the beginning and ending 
line numbers in the range with a colon, the debugger displays the source code 
corresponding to that range of line numbers. 


You can display all the source lines of a module by specifying a range of line 
numbers starting from 1 and ending at a number equal to or greater than the 
largest line number in the module. 


After displaying a single line of source code, you can display the next line of 
that module by entering a TYPE command without a line number—that is, by 
entering a TYPE command and then pressing. the Return key. You can then 
display the next line and successive lines by repeating this sequence, in effect, 
reading through your source program one line at a time. 


The TYPE command displays the lines of source code that correspond to the 
specified line numbers. The line numbers used by the debugger to identify lines of 
source code are generated by the compiler. They appear in a compiler-generated 
listing and in a screen-mode source display. 


If you specify a module name with the TYPE command, the module must be set. 
Use the SHOW MODULE command to determine whether a particular module is 
set. Then use the SET MODULE command, if necessary. 


Examples 
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In screen mode, the output of a TYPE command is directed at the current source 
display, not at an output or DO display. The source display shows the lines 
specified and any surrounding lines that fit in the display window. 


Related commands: 


EXAMINE/SOURCE 

SET (BREAK,TRACE,WATCH)/[NO]JSOURCE 
SET MODE [NO]SCREEN 
(SET,SHOW,CANCEL) SCOPE 

SET STEP [NO]JSOURCE 
STEP/[NO]JSOURCE 


1. DBG> TYPE 160 
module COBOLTEST 
160: START-IT-PARA. 
DBG> TYPE 
module COBOLTEST 
161: MOVE SC1 TO ESO. 
DBG> 


In this example, the first TYPE command displays line 160, using the current 
scope to locate the module containing that line number. The second TYPE 
command, entered without specifying a line number, displays the next line in 
that module. 


2. DBG> TYPE 160:163 
module COBOLTEST 
160: START-IT-PARA. 


161: MOVE SC1 TO ESO. 

LO2% DISPLAY ESO. 

1.63% MOVE SC1 TO ESI. 
DBG> 


This command displays lines 160 to 163, using the current scope to locate the 
module. 


3. DBG> TYPE SCREEN IO\7,22:24 
This command displays line 7 and lines 22 to 24 in module SCREEN_IO. 
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WHILE 


Format 


Parameters 


Description 


Example 
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Executes a sequence of commands while the language expression (Boolean 
expression) you have specified evaluates as true. 


WHILE Boolean-expression DO (command; .. . }) 


Boolean-expression 
Specifies a language expression that evaluates as a Boolean value (true or false) 
in the currently set language. 


command 
Specifies a debugger command. If you specify more than one command, separate 
them with semicolons. 


The WHILE command evaluates a Boolean expression in the current language. If 
the value is true, the command list in the DO clause is executed. The command 
then repeats the sequence, reevaluating the Boolean expression and executing the 
command- list until the expression is evaluated as false. 


If the Boolean expression is false, the WHILE command terminates. 
Related commands: 


EXTITLOOP 
FOR 
REPEAT 


DBG> WHILE (X .EQ. 0) DO (STEP/SILENT) 


This command directs the debugger to keep stepping through the program until 
X no longer equals 0 (FORTRAN example). 


A 


Command Defaults 


This appendix lists the defaults associated with debugger commands. 


Command 
@file-spec 
CALL 
CONNECT 
DEFINE 
DEFINE/KEY 


DELETE/KEY 
DEPOSIT 


DISPLAY 


DO 
EDIT 


(ENABLE,DISABLE) AST 
EVALUATE 


Default 


For any field of the file specification that is not 
specified, the default is SYS$DISK:[ JDEBUG.COM. To 
change the default, use the SET ATSIGN command. 


Arguments are passed by address (%ADDR). 
CALL/AST/NOSAVE_VECTOR_STATE. 


If no process is specified, the CONNECT command 
brings any processes that are waiting to connect to the 
debugging session under debugger control. 


DEFINE/ADDRESS 


DEFINE/KEY/ECHO/NOIF_STATE/NOLOCK_STATE 
/LOG/NOSET_STATE/NOTERMINATE 


DELETE/KEY/LOG/NOSTATE 


Language expressions are interpreted according to the 
currently set language. Address expressions that are 
associated with compiler generated types are treated 
according to that type. Other address expressions are 
treated as having the type longword integer. 


DISPLAY/DYNAMIC/NOMARK_CHANGE/POP when 
applied to an existing display. The current display 
kind, window, and size remain unchanged. 


DISPLAY/DYNAMIC/POP/SIZE:64 when creating 

a display. The default window is either H1 or H2, 
alternating between these two with each newly created 
display. The default display kind is "output". 


DO/PROCESS=* 


EDIT/NOEXIT. The default is to invoke the VAX 
Language-Sensitive Editor (LSE) in a spawned 
subprocess. This can be changed with a SET EDITOR 
command. The default source file to be edited is the 
file whose source code appears in the current source 
display. The default position of the editing cursor is 
either the beginning of the line that is centered in 
the current source display, or the start of line 1 if the 
editor was set to /NOSTART_POSITION. 


ENABLE AST 


Language expressions are interpreted according to the 
currently set language. 


Command Defaults 


Command 


EXAMINE 


EXPAND 


EXTRACT 


MOVE 
SCROLL 


SEARCH 


SELECT 
SET ATSIGN 
SET BREAK 


SET DEFINE 
SET EDITOR 
SET IMAGE 

SET KEY 

SET LANGUAGE 


SET LOG 

SET MARGINS 

SET MAX_SOURCE_FILES 
SET MODE 

SET OUTPUT 


SET PROCESS 
SET PROMPT 


SET RADIX 


Default 


The contents of program locations that are associated 
with a compiler generated type are interpreted and 
displayed according to that type. The contents of other 
locations are interpreted and displayed as longword 
integers. 


EXPAND/DOWN or /UP: 1 line. 
EXPAND/LEFT or /RIGHT: 1 column. 


If you specify /SCREEN_LAYOUT, the default output 
file is SYS$DISK:[ JDBGSCREEN.COM. Otherwise, 
the default output file is SYS$DISK:[ |JDEBUG.TXT. 


MOVE/DOWN or /UP: 1 line. 
MOVE/LEFT or /RIGHT: 1 column. 


SCROLL/DOWN or /UP: 3/4 of window height. 
SCROLL/LEFT or /RIGHT: 8 columns. 


SEARCH/NEXT/STRING. If no module name is 
specified, the debugger uses the current scope to find a 
module and searches that module for an occurrence of 
the string. The current scope is that established by a 
previous SET SCOPE command, or the PC scope if no 
SET SCOPE command was entered. Also, if no string 
is specified, the string specified in the last SEARCH 
command, if any, is used. 


SELECT/SCROLL 
SET ATSIGN SYS$DISK:[ JDEBUG.COM 


SET BREAK/INTO/JSB/SHARE/SYSTEM 
/NOSILENT/SOURCE 


SET DEFINE ADDRESS 

SET EDITOR/NOSTART_POSITION 
The current image is the main image. 
SET KEY/STATE=DEFAULT 


The default language is the language of the module 
that contains the image transfer address (main 
program). 


SET LOG SYS$DISK:[ JDEBUG.LOG 


SET MARGINS 1:255 (left margin: 1, right margin:. 
255) 


SET MAX_SOURCE_FILES 5 


SET MODE DYNAMIC, NOG_FLOAT, KEYPAD, 
LINE, NOOPERANDS, NOSCREEN, NOSEPARATE, 
SCROLL, SYMBOLIC 


SET OUTPUT NOLOG, NOSCREEN_LOG, 
TERMINAL, NOVERIFY 


SET PROCESS/VISIBLE 


SET PROMPT/NOPOP "DBG> ". 

For multiprocess programs: 

SET PROMPT/NOPOP/SUFFIX=PROCESS_NUMBER 
"DBG_" 


For all languages except BLISS and MACRO: SET 
RADIX DECIMAL. For BLISS and MACRO: SET 
RADIX HEXADECIMAL. 


Command 


SET SCOPE 


SET SEARCH 
SET SOURCE 


SET STEP 
SET TERMINAL 
SET TRACE 


SET TYPE 


SET VECTOR_MODE 
SET WATCH 


SPAWN 
STEP 
TYPE 


Command Defaults 


Default 


The debugger looks up a symbol specified without a 
path name prefix according to the scope search list 
0,1, ... ,2 (where n is the number of calls in the 
call stack). If the symbol is not found, the debugger 
searches the run-time symbol table, then the global 
symbol table if necessary. 


SET SEARCH NEXT, STRING 


When searching for a source file, the debugger uses 
the full file specification that is stored in the run-time 
symbol table (RST). 


SET STEP SOURCE, NOSILENT, OVER, LINE 


The values of /PAGE and /WIDTH default to those set 
at DCL level (see the VMS DCL Dictionary or enter 
the DCL command HELP SET TERMINAL). 


SET TRACE/INTO/JSB/SHARE/SYSTEM /NOSILENT 
/SOURCE 


The default type for program locations that are 
associated with a compiler generated type is that 
type. The default type for other locations is longword 
integer. 


SET VECTOR_MODE NOSYNCHRONIZED 


For static variables: SET WATCH/NOSILENT 
/SOURCE. For nonstatic variables: SET WATCH 
/NOSILENT/OVER/SOURCE. 


SPAWN/WAIT 
STEP/OVER/LINE 


If no module name is specified, the debugger uses 

the current scope to find a module and searches 

that module for source lines for display. The current 
scope is that established by a previous SET SCOPE 
command, or the PC scope if no SET SCOPE command 
was entered. Also, if no line is specified after a 

single source line has been displayed with the TYPE 
command, the next line in that module is displayed by 
default. 
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Predefined Key Functions 


When you invoke the debugger, certain predefined functions (commands, 
sequences of commands, and command terminators) are assigned to keys on 
the numeric keypad, to the right of the main keyboard. By using these keys 
you can enter certain commands with fewer keystrokes than if you were to type 
them at the keyboard. For example, pressing the comma key (,) on the keypad 
is equivalent to typing GO and then pressing the Return key. Terminals and 
workstations that have an LK201 keyboard have additional programmable keys 
compared to those on VT100 keyboards (for example, “Help” or “Remove”), and 
some of these keys are also assigned debugger functions. 


To use function keys, keypad mode must be enabled (SET MODE KEYPAD). 
Keypad mode is enabled when you invoke the debugger. If you do not want 
keypad mode enabled, perhaps because the program being debugged uses the 
keypad for itself, you can disable keypad mode by entering the SET MODE 
NOKEYPAD command. 


The keypad key functions that are predefined when you invoke the debugger are 
identified in summary form in Figure B-1. Table B-1, Table B—2, Table B-3, 

and Table B—4 identify all key definitions in detail. Most keys are used for 
manipulating screen displays in screen mode. To use screen mode commands, you 
must first enable screen mode by the PF3 key (SET MODE SCREEN). In screen 
mode, to re-create the default layout of various windows, press the keypad key 
sequence BLUE-MINUS (PF'4 followed by the MINUS key (—)). 


To use the keypad keys to enter numbers rather than debugger commands, enter 
the command SET MODE NOKEYPAD. 


B.1 DEFAULT, GOLD, BLUE Functions 


A given key typically has three predefined functions: 


¢ One function is entered by pressing the given key by itself. This is the 
DEFAULT function. 


e Asecond function is entered by pressing and releasing the PF1 key and then 
pressing the given key. This is the GOLD function, because PF1 is also called 
the GOLD key. 


e A third function is entered by pressing and releasing the PF4 key and then 
pressing the given key. This is the BLUE function, because PF4 is also called 
the BLUE key. 
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Predefined Key Functions 
B.1 DEFAULT, GOLD, BLUE Functions 


Figure B-1 Keypad Key Functions Predefined by the Debugger—Command Interface 


F17 


DEFAULT 
(SCROLL) 


PF2 


HELP DEFAULT 
HELP GOLD 
HELP BLUE 


DISP SRC,INST,OUT SCROLL/UP 
DISP INST,REG,OUT SCROLL/TOP 
DISP 2 SRC, 2 INST SCROLL/UP... 


SCROLL/LEFT EX/SOU .0\%PC 
SCROLULEFT:255 SHOW CALLS 
SCROLL/LEFT... SHOW CALLS 3 


EXAMINE SCROLL/DOWN 
EXAM“(prev) SCROLL/BOTTOM 
DISP 3SRC, 3 INST | SCROLLIDOWN... 


STEP 
STEP/ANTO 
STEP/OVER 


LK201 Keyboard: 


Press 
F17 
Fi8 
Fi9 
F20 


VT-100 Keyboard: 
Type 
SET KEY/STATE=DEFAULT 
SET KEY/STATE=MOVE 
SET KEY/STATE=EXPAND 
SET KEY/STATE=CONTRACT 
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F19 ; F20 


EXPAND CONTRACT 
(EXPAND +) (EXPAND ~) 


PF3 


SET MODE SCREEN 
SET MODE NOSCR 
DISP/GENERATE 


DISPLAY next DISP next at FS 
SET PROC next 
DISP 2 SRC DISP SRC, OUT 


SCROLL/RIGHT GO 
SCROLL/RIGHT:255 [| SEL/SOURCE next 
SCROLL/RIGHT... SEL/INST next 


SEL SCROLL next 
SEL OUTPUT next 
DISP 3 SRC 





Keys 2,4,6,8 
SCROLL 
MOVE 
EXPAND 
CONTRACT 


Keys 2,4,6,8 
SCROLL 
MOVE 
EXPAND 
CONTRACT 





MOVE/UP 
MOVE/UP:999 
MOVE/UP:5 





"MOVE" 


















MOVE/RIGHT 
MOVE/RIGHT:999 
MOVE/RIGHT:10 


MOVE/LEFT 
MOVE/LEFT:999 
MOVE/LEFT:10 









MOVE/DOWN 
MOVE/DOWN:999 
MOVE/DOWN:5 













EXPAND/UP 
EXPAND/UP:999 
EXPAND/UP:5 


"EXPAND" 














EXPAND/RIGHT 
EXPAND/RIGHT:999 
EXPAND/RIGHT:10 






EXPAND/LEFT 
EXPAND/LEFT:999 
EXPAND/LEFT:10 










EXPAND/DOWN 
EXPAND/DOWN:999 
EXPAND/DOWN:5 













EXPAND/UP:—1 
EXPAND/UP:-999 
EXPAND/UP:-5 


"CONTRACT" 







EXPAND/RIGHT:~1 
EXPAND/RIGHT:-999 
EXPAND/RIGHT:-10 


EXPAND/LEFT:-1 
EXPAND/LEFT:-999 
EXPAND/LEFT:~10 













EXPAND/DOWN:~1 
EXPAND/DOWN:-999 
EXPAND/DOWN:-5 
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Predefined Key Functions 
B.1 DEFAULT, GOLD, BLUE Functions 


In Figure B-1, the DEFAULT, GOLD, and BLUE functions are listed within each 
key’s outline, from top to bottom respectively. For example, pressing keypad key 
KPO enters the command STEP (DEFAULT function); pressing PF1 and then KPO 
enters the command STEP/INTO (GOLD function); pressing PF4 and then KPO 
enters the command STEP/OVER (BLUE function). 


All command sequences assigned to keypad keys are terminated (executed 
immediately) except for the BLUE functions of keys KP2, KP4, KP6, and KP8. 
These unterminated commands are symbolized with a trailing ellipsis ( ... ) 
in Figure B-1. To terminate the command, supply a parameter and then press 
RETURN. For example, to scroll down 12 lines, do the following: 


1. Press the PF4 key. 

2. Press keypad key KP2. 

3. Type :12 at the keyboard. 
4, Press the Return key. 


B.2 Key Definitions Specific to LK201 Keyboards 


Table B-1 lists keys that are specific to LK201 keyboards and do not appear on 
VT100 keyboards. For each key, the table identifies the equivalent command and, 
for some keys, an equivalent keypad key that you can use if you do not have an 
LK201 keyboard. 


Table B-1 Key Definitions Specific to LK201 Keyboards 


Equivalent 

LK201 Key Command Sequence Invoked Keypad Key 
F17 SET KEY/STATE=DEFAULT None 

F18 _ SET KEY/STATE=MOVE None 

F19 SET KEY/STATE=EXPAND None 

F20 SET KEY/STATE=CONTRACT None 

Help HELP KEYPAD SUMMARY None 

Next Screen SCROLL/DOWN KP2 

Prev Screen SCROLL/UP KP8 
Remove DISPLAY/REMOVE %CURSCROLL None 
Select SELECT/SCROLL %ZNEXTSCROLL KP3 


B.3 Keys That Scroll, Move, Expand, Contract Displays 


By default, keypad keys KP2, KP4, KP6, and KP§8 scroll the current scrolling 
display. Each key controls a direction (down, left, right, and up, respectively). 

By pressing keys F18, F19, or F20, you can place the keypad in the MOVE, 
EXPAND, or CONTRACT states. When the keypad is in the MOVE state, keys 
KP2, KP4, KP6, and KP8 can be used to move the current scrolling display down, 
left, and so on. Similarly, in the EXPAND and CONTRACT states, the four keys 
can be used to expand or contract the current scrolling display. (See Figure B-1 
and Table B—2. Alternative key definitions for VT100 keyboards are described 
later in this section.) 
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Predefined Key Functions 
B.3 Keys That Scroll, Move, Expand, Contract Displays 


To scroll, move, expand, or contract a display, proceed as follows: 


1. Press key KP8 repeatedly, as needed, to select the current scrolling display 
from the display list. 


2. Press key F17, F18, F19, or F20 to put the keypad in the DEFAULT (scroll), 
MOVE, EXPAND, or CONTRACT state, respectively. 


3. Press keys KP2, KP4, KP6, and KP8 to do the desired function. Use the 
PF1 (GOLD) and PF4 (BLUE) keys to control the amount of scrolling or 
movement. 


Table B—2 Keys That Change the Key State 


Key Description 

PF1 Invokes the GOLD function of the next key you press. 

PF4 Invokes the BLUE function of the next key you press. 

F17 Puts the keypad in the DEFAULT state, enabling the scroll-display functions 


of keys KP2, KP4, KP6, and KP8. The keypad is in the DEFAULT state when 
you invoke the debugger. 


F18 Puts the keypad in the MOVE state, enabling the move-display functions of 
keys KP2, KP4, KP6, and KP8. 

F19 Puts the keypad in the EXPAND state, enabling the expand-display functions 
of keys KP2, KP4, KP6, and KP8. 

F20 Puts the keypad in the CONTRACT state, enabling the contract-display 


functions of keys KP2, KP4, KP6, and KP8. 


If you have a VT100 keyboard, you can simulate the effect of LK201 keys F17 
to F20 by defining the key sequences GOLD-KP9 and BLUE-KP9 (currently 
undefined) as shown below. With these definitions, pressing GOLD-KP9 puts the 
keypad in the DEFAULT (scroll) state; pressing BLUE-KP9 cycles the keypad 
through the DEFAULT, MOVE, EXPAND, and CONTRACT states (like cycling 
through keys F17 to F20). You might want to store these key definitions in a 
command procedure, such as your debugger initialization file. 


DEFINE/KEY/IF_ STATE=(GOLD,MOVE GOLD, EXPAND GOLD, CONTRACT GOLD) - 

/TERMINATE KP9 "SET KEY/STATE=DEFAULT/NOLOG" 
DEFINE/KEY/IF_STATE= (BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=MOVE/NOLOG" 
DEFINE/KEY/IF_STATE=(MOVE_BLUE) ~ 

/TERMINATE KP9 "SET KEY/STATE=EXPAND/NOLOG" 
DEFINE/KEY/IF STATE=(EXPAND BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=CONTRACT/NOLOG" 
DEFINE/KEY/IF_STATE=(CONTRACT BLUE) - 

/TERMINATE KP9 "SET KEY/STATE=DEFAULT/NOLOG" 


B.4 Online Keypad Key Diagrams 


Online HELP for the keypad keys is available by pressing the Help key and also 
the PF2 key, either by itself or with other keys (see Table B—3). You can also use 
the SHOW KEY command to identify key definitions. 
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Predefined Key Functions 


B.4 Online Keypad Key Diagrams 


Table B-3 Keys That Invoke Online Help to Display Keypad Diagrams 


Key or 
Key Sequence 


Help 

PF2 

PF1-PF2 
PF4-PF2 
F18-PF2 
F18-PF1-PF2 
F18-PF4-PF2 
F19-PF2 
F19-PF1-PF2 
F19-PF4-PF2 
F20-PF2 
F20-PF1-PF2 


F20-PF4-PF2 


Command Sequence Invoked 
HELP KEYPAD SUMMARY 


HELP KEYPAD DEFAULT 
HELP KEYPAD GOLD 

HELP KEYPAD BLUE 

HELP KEYPAD MOVE 

HELP KEYPAD MOVE_GOLD 
HELP KEYPAD MOVE_BLUE 
HELP KEYPAD EXPAND 

HELP KEYPAD EXPAND_GOLD 
HELP KEYPAD EXPAND_BLUE 
HELP KEYPAD CONTRACT 
HELP KEYPAD CONTRACT_GOLD 


HELP KEYPAD CONTRACT_BLUE 


B.5 Debugger Key Definitions 


Table B—4 identifies all key definitions. 


Table B-4 Debugger Key Definitions 


Description 
Shows a diagram of the keypad keys and 
summarizes each key’s function 


Shows a diagram of the keypad keys and 
their DEFAULT functions 


Shows a diagram of the keypad keys and 
their GOLD functions 


Shows a diagram of the keypad keys and 
their BLUE functions 


Shows a diagram of the keypad keys and 
their MOVE DEFAULT functions 


Shows a diagram of the keypad keys and 
their MOVE GOLD functions 


Shows a diagram of the keypad keys and 
their MOVE BLUE functions 


Shows a diagram of the keypad keys and 
their EXPAND DEFAULT functions 


Shows a diagram of the keypad keys and 
their EXPAND GOLD functions 


Shows a diagram of the keypad keys and 
their EXPAND BLUE functions 


Shows a diagram of the keypad keys and 
their CONTRACT DEFAULT functions 


Shows a diagram of the keypad keys and 
their CONTRACT GOLD functions 


Shows a diagram of the keypad keys and 
their CONTRACT BLUE functions 


Key State Command Invoked or Function 
KPO DEFAULT STEP 
GOLD STEP/INTO 
BLUE STEP/OVER 
KP1 DEFAULT EXAMINE. Examines the logical successor of the 
current entity, if one is defined (the next location). 
GOLD EXAMINE *. Enables you to examine the logical 


predecessor of the current entity, if one is defined 
(the previous location). 


(continued on next page) 
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Table B—4 (Cont.) Debugger Key Definitions 


Key 


State 


BLUE 


DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 


BLUE 


BLUE 


DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 


Command Invoked or Function 


Displays three sets of predefined process-specific 
source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at S2 and RS2, 
respectively; source and instruction displays for the 
previous process on the process list at S1 and RS1, 
respectively; and source and instruction displays for 
the next process on the process list at S3 and RS8, 
respectively. 


SCROLL/DOWN 
SCROLL/BOTTOM 


SCROLL/DOWN (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:n) or a display name. 


MOVE/DOWN 
MOVE/DOWN:999 
MOVE/DOWN:5. 
EXPAND/DOWN 
EXPAND/DOWN:999 
EXPAND/DOWN:5 
EXPAND/DOWN:-1 
EXPAND/DOWN:-999 
EXPAND/DOWN:-5 


SELECT/SCROLL 2NEXTSCROLL. Selects as the 
current scrolling display the next display in the 
display list after the current scrolling display. 


SELECT/OUTPUT %NEXTOUTPUT. Selects the 
next output display in the display list as the current 
output display. 


Displays three predefined process-specific source 
displays, SRC_n. These are located at S1, S2, and 
S3, respectively, for the previous, current (visible), 
and next process on the process list. 


SELECT/SOURCE %NEXTSOURCE. Selects the 
next source display in the display list as the current 
source display. 


SCROLL/LEFT 
SCROLL/LEFT:255 


SCROLL/LEFT (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:m) or a display name. 


MOVE/LEFT 
MOVE/LEFT:999 
MOVE/LEFT:10 
EXPAND/LEFT 
(continued on next page) 
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Table B-4 (Cont.) Debugger Key Definitions 


Key 


State 


EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 
BLUE 
DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 


Command Invoked or Function 


EXPAND/LEFT:999 
EXPAND/LEFT:10 
EXPAND/LEFT:-1 
EXPAND/LEFT:-999 


- EXPAND/LEFT:-10 


EXAMINE/SOURCE .%SOURCE_SCOPE\ %PC; 
EXAMINE/INST .%INST_SCOPE\ %PC. In line 
(noscreen) mode, displays the source line and 
the instruction to be executed next. In screen 
mode, centers the current source display on the 
next source line to be executed, and the current 
instruction display on the next instruction to be 
executed. 


SHOW CALLS 
SHOW CALLS 3 
SCROLL/RIGHT 
SCROLL/RIGHT:255 


SCROLL/RIGHT (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:n) or a display name. 


MOVE/RIGHT 
MOVE/RIGHT:999 
MOVE/RIGHT:10 


EXPAND/RIGHT 


EXPAND/RIGHT:999 
EXPAND/RIGHT:10 
EXPAND/RIGHT:-1 
EXPAND/RIGHT:-999 
EXPAND/RIGHT:-10 


DISPLAY SRC AT LH1, INST AT RH1, OUT AT 
S45, PROMPT AT S6; SELECT/SCROLL/SOURCE 
SRC; SELECT/INST INST; SELECT/OUT OUT. 
Displays the SRC, INST, OUT, and PROMPT 
displays with the proper attributes. 


DISPLAY INST AT LH1, REG AT RH1, OUT AT 
S45, PROMPT AT S6; SELECT/SCROLL/INST 
INST; SELECT/OUT OUT. Displays the INST, 
REG, OUT, and PROMPT displays with the proper 
attributes. 


(continued on next page) 
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Table B—4 (Cont.) Debugger Key Definitions 


Key 


PF1 
PF2 
PF3 


PF4 
COMMA 


State 


BLUE 


DEFAULT 
GOLD 
BLUE 


MOVE 
MOVE_GOLD 
MOVE_BLUE 
EXPAND 
EXPAND_GOLD 
EXPAND_BLUE 
CONTRACT 
CONTRACT_GOLD 
CONTRACT_BLUE 
DEFAULT 


GOLD 


BLUE 


DEFAULT 


GOLD 


BLUE 


DEFAULT 


Command Invoked or Function 


Displays two sets of predefined process-specific 
source and instruction displays, SRC_n and 
INST_n. These consist of source and instruction 
displays for the visible process at Q1 and RQ1, 
respectively, and source and instruction displays for 
the next process on the process list at Q2 and RQ2, 
respectively. 


SCROLL/UP 
SCROLL/TOP 


SCROLL/UP (not terminated). To terminate the 
command, supply the number of lines to be scrolled 
(:n) or a display name. 


MOVE/UP 
MOVE/UP:999 
MOVE/UP:5 
EXPAND/UP 
EXPAND/UP:999 
EXPAND/UP:5 
EXPAND/UP:-1 
EXPAND/UP:-999 
EXPAND/UP:-5 


DISPLAY %NEXTDISP. Displays the next display 
in the display list through its current window 
(removed displays are not included). 


SET PROCESS/VISIBLE %NEXT_PROCESS. 
Makes the next process in the process list the 
visible process. 


Displays two predefined process-specific source 
displays, SRC_n. These are located at Q1 and Q2, 
respectively, for the visible process and for the next 
process on the process list. 


See Table B—2. 
See Table B-3. 


SET MODE SCREEN; SET STEP NOSOURCE. 
Enables screen mode and suppresses the output 

of source lines that would normally appear in the 
output display (since that output is redundant when 
the source display is present). 


SET MODE NOSCREEN; SET STEP SOURCE. 
Disables screen mode and restores the output of 
source lines. 


DISPLAY/GENERATE. Regenerates the contents of 
all automatically updated displays. 


See Table B-2. 
GO 
(continued on next page) 
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Table B—4 (Cont.) Debugger Key Definitions 


Key 


MINUS 


Enter 


PERIOD 


Next 
Screen 
(E6) 


Prev 
Screen 
(E5) 


Remove 
(E3) 


Select 
(E4) 


F17 
F18 
F19 
F20 
Ctrl/wW 
CtrV/Z 


State 


GOLD 


BLUE 


DEFAULT 


GOLD 
BLUE 


All states 


DEFAULT 


DEFAULT 


DEFAULT 


DEFAULT 


Command Invoked or Function 


SELECT/SOURCE %NEXT_SOURCE. Selects the 
next source display in the display list as the current 
source display. 

SELECT/INSTRUCTION %NEXTINST. Selects the 
next instruction display in the display list as the 
current instruction display. 


DISPLAY %NEXTDISP AT $12345, PROMPT AT 
S86; SELECT/SCROLL %CURDISP. Displays the 
next display in the display list at essentially full 
screen (top of screen to top of PROMPT display). 
Selects that display as the current scrolling display. 
Undefined 


DISPLAY SRC AT H1, OUT AT S45, PROMPT AT 
S6; SELECT/SCROLL/SOURCE SRC; SELECT 
/OUT OUT. Displays the SRC, OUT, and PROMPT 
displays with the proper attributes. This is the 
default display configuration. 


Enables you to enter (terminate) a command. Same 
effect as Return. 


Cancels the effect of pressing state keys which do 
not lock the state, such as GOLD and BLUE. Does 
not affect the operation of state keys which lock the 
state, such as MOVE, EXPAND, and CONTRACT. 


SCROLL/DOWN 


SCROLL/UP 


DISPLAY/REMOVE %CURSCROLL. Removes the 
current scrolling display from the display list. 


SELECT/SCROLL %NEXTSCROLL. Selects as the 
current scrolling display the next display in the 
display list after the current scrolling display. 


See Table B—2. 

See Table B—2. 

See Table B—2. 

See Table B-2. 
DISPLAY/REFRESH 
EXIT 
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This appendix contains summarized reference information related to screen mode. 
The following topics are covered: 


e Display kinds 

¢ Display attributes 

e Predefined displays 

¢ Screen-related built-in symbols 


¢ Screen dimensions and predefined windows 


C.1 Display Kinds 
The DISPLAY command accepts these display-kind keywords and parameters: 


DO (command{; .. . ]) Specifies an automatically updated output display. 
The commands are executed in the order listed each 
time the debugger gains control. Their output forms 
the contents of the display. If you specify more than 
one command, they must be separated by semicolons. 


INSTRUCTION Specifies an instruction display. If selected as the 
current instruction display with the SELECT 
/JINSTRUCTION command, it displays the output 
from subsequent EXAMINE/INSTRUCTION 
commands. 


INSTRUCTION (command) Specifies an automatically updated instruction 
display. The command specified must be an 
EXAMINE/INSTRUCTION command. The 
instruction display is updated each time the 
debugger gains control. 


OUTPUT Specifies an output display. If selected as the 
current output display with the SELECT/OUTPUT 
command, it displays any debugger output that is not 
directed to another display. If selected as the current 
input display with the SELECT/INPUT command, 
it echoes debugger input. If selected as the current 
error display with the SELECT/ERROR command, it 
displays debugger diagnostic messages. 


REGISTER Specifies an automatically updated register display. 
The display is updated each time the debugger gains 
control. 

SOURCE Specifies a source display. If selected as the current 


source display with the SELECT/SOURCE command, 
it displays the output from subsequent TYPE or 
EXAMINE/SOURCE commands. 
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SOURCE (command) Specifies an automatically updated source display. 
The command specified must be a TYPE or 
EXAMINE/SOURCE command. The source display 
is updated each time the debugger gains control. 


C.2 Display Attributes 


The SELECT command assigns an attribute to a display according to the 
qualifier used with that command. The following list identifies each of the 
SELECT command qualifiers, its effect, and the display kinds to which you can 
assign that attribute. 


SELECT 
Qualifier Description 
/ERROR Selects the specified display as the current error display. Directs 


any subsequent debugger diagnostic message to that display. It 
must be either an output display or the PROMPT display. If no 
display is specified, selects the PROMPT display as the current 
error display. 


AINPUT Selects the specified display as the current input display. Echoes 
any subsequent debugger input in that display. It must be an 
output display. If no display is specified, unselects the current 
input display: debugger input is not echoed to any display. 


AINNSTRUCTION Selects the specified display as the current instruction display. 
Directs the output of any subsequent EXAMINE/INSTRUCTION 
command to that display. It must be an instruction display. The 
BLUE-COMMA keypad sequence selects the next instruction 
display in the display list as the current instruction display. If no 
display is specified, unselects the current instruction display: no 
display has the instruction attribute. 


/OUTPUT Selects the specified display as the current output display. Directs 
any subsequent debugger output to that display, except where a 
particular type of output is being directed to another display (such 
as diagnostic messages going to the current error display). The 
specified display must be either an output display or the PROMPT 
display. The GOLD-KP3 keypad key sequence selects the next 
output display in the display list as the current output display. If 
no display is specified, selects the PROMPT display as the current 
output display. 


/PROGRAM Selects the specified display as the current program display. 
Tries to force any subsequent program input or output to that 
display. Currently, only the PROMPT display can be specified. 
If no display is specified, unselects the current program display: 
program output is no longer forced to the PROMPT display. 


/PROMPT Selects the specified display as the current prompt display, where 
the debugger prompts for input. Currently, only the PROMPT 
display can be specified. You cannot unselect the PROMPT 
display. 
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SELECT 
Qualifier 


/SCROLL 


/SOURCE 
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Description 


Selects the specified display as the current scrolling display. 
Makes that display the default display for any subsequent 
SCROLL, MOVE, or EXPAND command. You can specify any 
display (however, note that the PROMPT display cannot be 
scrolled). The /SCROLL qualifier is the default if you do not 
specify a qualifier with the SELECT command. The KP3 key 
selects as the current scrolling display the next display in the 
display list after the current scrolling display. If no display is 
specified, unselects the current scrolling display: no display has 
the scroll attribute. 


Selects the specified display as the current source display. Directs 
the output of any subsequent TYPE or EXAMINE/SOURCE 
command to that display. It must be a source display. The BLUE- 
3 keypad key sequence selects the next source display in the 
display list as the current source display. If no display is specified, 
unselects the current source display: no display has the source 
attribute. 


By default, when you invoke screen mode, the predefined displays are selected for 
attributes as follows: ° 


Aitribute 


Error 
Input 
Instruction 
Output 
Program 
Prompt 
Scroll 


Source 
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Predefined Display 


PROMPT 

no display selected 
no display selected 
OUT 

PROMPT 
PROMPT 

SRC 

SRC 


This section summarizes the properties of the predefined displays SRC, OUT, 
PROMPT, INST and REG. 


C.3.1 SRC (Source Display) 


SRC is an automatically updated source display. It shows the source code of the 
module being debugged, if that source code is available. The arrow points to the 
source line corresponding to the current PC value (where execution is suspended). 


The default characteristics of the SRC display are the following: 


Display kind 
Attributes 
Position 

Size 


Dynamic 


source (examine/source .%source_scope\ %pc) 
scroll, source 

H1 

64 lines 


yes 
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%SOURCE_SCOPE is a built-in scope that has the following properties: 


e By default %SOURCE_SCOPE denotes scope 0, which is the scope of the 
routine where execution is currently suspended. 


e If you have reset the scope search list relative to the call stack by means 
of the SET SCOPE/CURRENT command, %SOURCE_SCOPE denotes the 
current scope specified (the scope of the routine at the start of the search list). 


e If source code is not available for the routine in the current scope, 
%SOURCE_SCOPE denotes scope N, where N is the first level down the 
call stack for which source code is available. 


When displaying source lines that are not associated with the module where 
execution is suspended, the debugger issues the following message: 


SDEBUG-I-SOURCESCOPE, Source lines not available for .0\%PC. 
Displaying source in a caller of the current routine. 


C.3.2 OUT (Output Display) | 


OUT shows all debugger output that is not directed to another display. 
The default characteristics of the OUT display are the following: 


Display kind output 
Attribute output 
Position S45 

Size 100 lines 
Dynamic yes 


C.3.3 PROMPT (Prompt Display) 


C4 


PROMPT is the display in which the debugger prompts for input and, by default, 
forces program output and prints debugger diagnostic messages. 


PROMPT has different properties and restrictions than other displays. This is to 
eliminate possible confusion when manipulating that display: 


¢ You cannot hide, remove, permanently delete, or scroll PROMPT. 


e You can contract PROMPT down to 2 lines. You cannot contract PROMPT 
horizontally. 


The default characteristics of the PROMPT display are the following: 


Display kind program 

Attributes error, prompt, program (no other display can have the prompt or 
program attributes) 

Position S6 

Size not applicable (PROMPT is not scrollable) 

Dynamic yes 
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C.3.4 INST (Instruction Display) 


INST is an automatically updated instruction display. It shows the instruction 
stream of the routine being debugged. The instructions displayed are decoded 
from the image being debugged. The arrow points to the instruction at the 
current PC value. 


The default characteristics of the INST display are the following: 


Display Kind Instruction (EXAMINE/INSTRUCTION .%INST_SCOPE\ %PC) 
Attributes none 

Position H1, removed 

Size 64 lines 

Dynamic yes 


%INST_SCOPE is a built-in scope that has the following properties: 


e By default %INST_SCOPE denotes scope 0, which is the scope of the routine 
where execution is currently suspended. 


¢ If you have reset the scope search list relative to the call stack by means of 
the SET SCOPE/CURRENT command, %ZINST_SCOPE denotes the current 
scope specified (the scope of the routine at the start of the search list). 


C.3.5 REG (Register Display) 


REG automatically shows the current values, in hexadecimal format, of the VAX 
general registers (RO to R11, AP, FP, SP, and PC), the four condition code bits 
(C,V, Z, and N) of the processor status longword (PSL), and as many of the top 
call stack values as can be displayed in the window. 


The register values displayed are for the routine in which execution is currently 
suspended. The values are updated whenever the debugger takes control. Any 
changed values are highlighted. 


The default characteristics of the REG display are the following: 


Display Kind Register 
Attribute none 

Position RH1, removed 
Size 64 lines 
Dynamic yes 


If the register window is resized, the debugger automatically reformats the 
displayed information to adapt to the new window size. 


Display REG does not display the current values of the VAX vector registers. To 
display data contained in vector registers or vector control registers in screen 
mode, use a DO display. (See Section 7.6.1.) 


C.4 Screen-Related Built-In Symbols 


The following built-in symbols are available for specifying displays and screen 
parameters in language expressions: . 


¢ %SOURCE_SCOPE—To display source code. %SOURCE_SCOPE is described 
in Section C.3.1. 


¢ %INST_SCOPE—To display instructions. 2INST_SCOPE is described in 
Section C.3.4. 
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¢ 9%PAGE, %WIDTH—To specify the current screen height and width. | 


¢ %CURDISP, %CURSCROLL, %NEXTDISP, 2NEXTINST, ZNEXTOUTPUT, 
%NEXTSCROLL, ZNEXTSOURCE—To specify displays in the display list. 


C.4.1 Screen Height and Width 


The built-in symbols %PAGE and %WIDTH return, respectively, the current 
height and width of the terminal screen. These symbols can be used in various 
expression, such as for window specifications. For example, the following 
command defines a window named MIDDLE that occupies a region around 
the middle of the screen: 


DBG> SET WINDOW MIDDLE AT (%PAGE/4,%PAGE/2, SWIDTH/4, SWIDTH/2) 


C.4.2 Display Built-In Symbols 


Each time you refer to a specific display with a DISPLAY command, the display 
list is updated and reordered, if necessary. The most recently referenced display 
is put at the tail of the display list, since that display is pasted last on the 
pasteboard (the display list can be identified by entering a SHOW DISPLAY 
command). 


You can use display built-in symbols to specify displays relative to their positions 
in the display list. These symbols, listed as follows, enable you to refer to 
displays by their relative positions in the list instead of by their explicit names. 
The symbols are used mainly in keypad key definitions or command procedures. 


Display symbols treat the display list as a circular list. Therefore, you can enter 
any commands that use display symbols to cycle through the display list until 
you reach the display you want. 


%CURDISP The current display. This is the display most recently referenced 
with a DISPLAY command—the least occluded display. 
%CURSCROLL The current scrolling display. This is the default display for the 


SCROLL, MOVE, and EXPAND commands, as well as for the 
associated keypad keys (KP2, KP4, KP6, and KP8). 


%NEXTDISP The next display in the list after the current display. The next 
display is the display that follows the topmost display. Because 
the display list is circular, this is the display at the bottom of the 
pasteboard—the most occluded display. 

%NEXTINST The next instruction display in the display list after the current 

instruction display. The current instruction display is the 
display that receives the output from EXAMINE/INSTRUCTION 
commands. 


%NEXTOUTPUT The next output display in the display list after the current output 
display. An output display receives debugger output that is not 
already directed to another display. 

%NEXTSCROLL The next display in the display list after the current scrolling 
display. 

%NEXTSOURCE The next source display in the display list after the current source 


display. The current source display is the display which receives the 
output from TYPE and EXAMINE/SOURCE commands. 
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C.5 Screen Dimensions and Predefined Windows 


On a VT-series terminal, the screen consists of 24 lines by 80 or 132 columns. On 
a workstation, the screen is larger in both height and width. The debugger can 
accommodate screen sizes up to 100 lines by 255 columns. 


The debugger has many predefined windows that you can use to position displays 
on the screen. The SHOW WINDOW command identifies all predefined and user 
defined windows. The predefined windows are expressed in terms of fractions 

of the screen dimensions (for example, quarters, halves, and so on). Therefore, 
the positions and dimensions of the predefined windows that are indicated by the 
SHOW WINDOW command are adjusted for the screen dimensions. 


In addition to the full height and width of the screen, the predefined windows 
include all possible regions that result from dividing the screen vertically into 
halves, thirds, quarters, sixths, and eighths, and horizontally into left and right 
halves. 


The following conventions apply to the names of predefined windows. The 
prefixes L and R denote left and right windows, respectively. Other letters denote 
the full screen (FS) or fractions of the screen height (H: half, T: third, Q: quarter, 
S: sixth, E: eighth). The trailing numbers denote specific fractions of the screen 
height, starting from the top. For example: 


¢ Windows T1, T2, and T3 occupy the top, middle and bottom thirds of the 
screen, respectively. 


e¢ Window RH2 occupies the right bottom half of the screen. 
¢ Window LQ23 occupies the left middle two quarters of the screen. 
¢ Window S45 occupies the fourth and fifth sixths of the screen. 


The horizontal boundaries (start-column, column-count) of the predefined 
windows for the default terminal screen width of 80 columns are as follows: 


e Left hand windows: (1,40) 
e Right hand windows: (42,39) 


The vertical boundaries (start-line, line-count) of the predefined windows for the 
default terminal screen height of 24 lines are as follows: 


Window Name Start-Line, Line-Count Window Location 
FS (1,23) Full screen 

Hi (1,11) Top half 

H2 (13,11) Bottom half 

TL (1,7) Top third 

T2 (9,7) Middle third 
T3 (17,7) Bottom third 
Ql (1,5) Top quarter 

Q2 (7,5) Second quarter 
Q3 (13,5) Third quarter 
Q4 (19,5) Bottom quarter 
S1 (1,3) Top sixth 
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Window Name Start-Line, Line-Count Window Location 


S82 (5,3) Second sixth 
83 (9,3) Third sixth 
S4 (13,3) Fourth sixth 
85 (17,3) Fifth sixth 

S6 (21,3) Bottom sixth 
El (1,2) Top eighth 

E2 (4,2) Second eighth 
E3 (7,2) Third eighth 
E4 (10,2) Fourth eighth 
E5 (13,2) Fifth eighth 
E6 (16,2) Sixth eighth 
E7 (19,2) . Seventh eighth 
E8 (22,2) : Bottom eighth 
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This appendix identifies all of the debugger built-in symbols and logical names. 


D.1 SS$ DEBUG Condition 


SS$_DEBUG (defined in SYS$LIBRARY:STARLET.OLB) is a condition you can 
signal from your program to invoke the debugger. Signaling SS$_DEBUG from 
your program is equivalent to typing Ctrl/Y followed by the DCL command 
DEBUG at that point. 


You can pass commands to the debugger at the time you signal it with SS$_ 
DEBUG. The commands you want the debugger to execute should be specified 
as you would enter them at the DBG> prompt. Multiple commands should be 
separated by semicolons. The commands should be passed by reference as an 
ASCIC string. See your language documentation for details on constructing an 
ASCIC string. 


For example, to invoke the debugger and enter a SHOW CALLS command at a 
given point in your program, you could insert the following code in your program 
(BLISS example): 


LIBSSIGNAL(SS$_ DEBUG, 1, UPLIT BYTE(SASCIC ‘SHOW CALLS’) ); 

You can obtain the definition of SS$_DEBUG at compile time from 

the appropriate STARLET or SYSDEF file for your language (for 
example STARLET.L32 for BLISS or FORSYSDEF.TLB for FORTRAN). 
You can also obtain the definition of SS$_DEBUG at link time in 
SYS$LIBRARY:STARLET.OLB (this method is less desirable). 


D.2 Logical Names 


The following list identifies debugger-specific logical names. 


Logical 
Name Description 
DBGS$INIT Specifies your debugger initialization file. Default: no 


debugger initialization file. DBG$INIT accepts a full or 
partial VMS file specification as well as a search list. See 
Section 8.2 for information about debugger initialization files. 


DBG$INPUT Specifies the debugger input device. Default: SYS$INPUT. 
See Section 9.2 for information about using DBG$INPUT and 
DBG$OUTPUT to debug screen-oriented programs at two 
terminals. 


DBG$INPUT is ignored in the DECwindows interface (see 
DBG$DECW$DISPLAY). You can use DBG$INPUT if you are 
displaying the debugger’s command interface in a DECterm 
window (see Section 1.6.3.3). 
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Logical 
Name 


DBG$OUTPUT 


DBG$PROCESS 


DBG$DECW$DISPLAY 


Description 


Specifies the debugger output device. Default: 
SYSSOUTPUT. See Section 9.2 for information about using 
DBG$INPUT and DBG$OUTPUT to debug screen-oriented 
programs at two terminals. 


DBG$OUTPUT is ignored in the DECwindows interface 
(see DBGSDECW$DISPLAY). You can use DBGSOUTPUT 
if you are displaying the debugger’s command interface in a 
DECterm window (see Section 1.6.3.3). 


Specifies the debugging configuration (default or 
multiprocess). Default: DBG$PROCESS is undefined. See 
Section 10.2.1 for information about using DBG$PROCESS 
to specify the debugging configuration. 


. Applies only to workstations running DECwindows. Specifies 


the debugger interface (DECwindows or command) or the 
display device. Default: DBG$DECW$DISPLAY is either 
undefined or has the same definition as the application- 

wide logical name DECW$DISPLAY. See Section 1.6.3 

for information about using DBG$DECW$DISPLAY to 
override the debugger’s default interface in the DECwindows 
environment. 


Use the DCL command DEFINE or ASSIGN to assign values to these logical 
names. For example, the following command specifies the location of the debugger 


initialization file: 


$ DEFINE DBGSINIT DISKS: [JONES.COMFILES] DEBUGINIT.COM 


Note the following points about the logical name DBG$INPUT. If you plan to 
debug a program that takes its input from a file (for example, PROG_IN.DAT) 
and your debugger input from the terminal, establish the following definitions 
before invoking the debugger: 


$ DEFINE SYSSINPUT PROG_IN.DAT 
$ DEFINE/PROCESS DBGSINPUT 'FSLOGICAL("SYSSCOMMAND") 


That is, define DBG$INPUT to point to the translation of SYS$COMMAND. If 
you define DBG$INPUT to point to SYS$COMMAND, the debugger tries to get 
its input from the file, PROG_IN.DAT. 


D.3 Built-In Symbols 


The debugger’s built-in symbols provide options for specifying program entities 


and values. 


Most of the debugger built-in symbols have a percent sign ( %) prefix. 


The following symbols are described in this appendix: 
¢ %R0 to %R11, ZAP, GFP, “SP, %PC, %PSL—Used to specify the VAX general 


registers. 


¢ %V0 to 2V15, %VCR, *ZVLR, and %7VMR—Used to specify the VAX vector 
registers and vector control registers. 


¢ %NAME—Used to construct identifiers. 


¢ %PARCNT—Used in command procedures to count parameters passed. 
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%DECWINDOWS—Used in debugger command procedures or initialization 
files to determine whether the debugger’s command interface or DECwindows 
interface was invoked. 


%BIN, %DEC, “HEX, %0CT—Used to control the input radix. 


Period (.), Return key, circumflex (“), backslash (\ ), ZCURLOC, 
%NEXTLOC, %PREVLOC, %CURVAL—Used to specify consecutive program 
locations and the current value of an entity. 


Plus sign (+), minus sign (—), multiplication sign (*), division sign (/), at 
sign (@), period (.), bit field operator (<p,s,e>), ZLABEL, %LINE, backslash 
(\ ) —Used as operators in address expressions. 


%ADAEXC_NAME, %EXC_FACILITY, %EXC_NAME, 2ZEXC_NUMBER, 
%EXC_SEVERITY—Used to obtain information about exceptions. 


%CURRENT_SCOPE_ENTRY, %NEXT_SCOPE_ENTRY, %PREVIOUS_ 
SCOPE_ENTRY—Used to specify the current, next, and previous scope 
relative to the call stack. 


The following symbols are described elsewhere in this manual, as indicated: 


%ADDR, %DESCR, *ZREF, %VAL—Used to specify the argument passing 
mechanism for the CALL command. See the CALL command description in 
the command dictionary. 


%PROCESS_NAME, %PROCESS_PID, %7PROCESS_NUMBER, %NEXT_ 
PROCESS, %PREVIOUS_PROCESS, %VISIBLE_PROCESS—Used to specify 
processes in multiprocess programs. See Section 10.2.2. 


%ACTIVE_TASK, %CALLER_TASK, %NEXT_TASK, %PREVIOUS_TASK, 
%TASK, %ZVISIBLE_TASK—Used to specify tasks or threads in tasking or 
multithread programs. See Section 12.3.4. 


%PAGE, %WIDTH—Used to specify the current screen height and width. See 
Section C.4.1. 


%SOURCE_SCOPE, %“INST_SCOPE—Used to specify the scope for source 
and instruction display in screen mode. See Section C.3.1 and Section C.3.4, 
respectively. 


%CURDISP, %CURSCROLL, %NEXTDISP, %NEXTINST, %NEXTOUTPUT, 
%NEXTSCROLL, %NEXTSOURCE—Used in screen mode to specify displays 
in the display list. See Section C.4.2. 


D.3.1 Specifying the VAX Registers 


The debugger built-in symbol for a VAX register is the register name preceded 
by the percent sign (% ). When specifying a register symbol, you can omit the 
percent sign (%) prefix if your program has not declared a symbol with the same 
name. 
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The register symbols are identified in the following list. 


Symbol Description 


VAX General Registers 


%RO... MR11 General purpose registers (RO... R11) 
%AP (%R12) Argument pointer (AP) 

%FP (%R13) Frame pointer (FP) 

%SP (%R14) Stack pointer (SP) 

%PC (%R15) Program counter (PC) 

%PSL Processor status longword (PSL) 


VAX Vector Registers and Vector Control Registers 


%V0... MV15 Vector registers VO... V15 
%VCR Vector count register 
%VLR Vector length register 
%VMR Vector mask register 


See Section 4.4 and Section 4.3.1 for more information about the general registers. 
See Chapter 11 for more information about the vector registers. 


D.3.2 Constructing Identifiers 


The %NAME built-in symbol enables you to construct identifiers that are not 
ordinarily legal in the current language. The syntax is as follows: 


%NAME ’character-string 

In the following example, the variable with the name ’12’ is examined: 
DBG> EXAMINE %NAME '12’ 

In the following example, the compiler-generated label PAAA is examined: 
DBG> EXAMINE $NAME 'P.AAA’ 


D.3.3 Counting Parameters Passed to Command Procedures 
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The %PARCNT built-in symbol can be used within a command procedure that 
accepts a variable number of actual parameters (ZPARCNT is defined only within 
a debugger command procedure). 


%PARCNT specifies the number of actual parameters passed to the current 
command procedure. In the following example, command procedure ABC.COM is 
invoked and three parameters are passed: 


DBG> @ABC 111,222,333 


Within ABC.COM, %PARCNT now has the value 3. %PARCNT is then used as a 
loop counter to obtain the value of each parameter passed to ABC.COM: 


DBG> FOR I = 1 TO SPARCNT DO (DECLARE X:VALUE; EVALUATE X) 
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D.3.4 Determining the Debugger Interface (Command or DECwindows) 


The 2DECWINDOWS built-in symbol enables you to determine whether 

the debugger’s DECwindows or command interface was invoked. When the 
DECwindows interface is being used, the value of %DECWINDOWS is 1 (TRUE). 
When the command interface is being used, the value of S7DECWINDOWS is 0 
(FALSE). For example: 


DBG> EVALUATE %SDECWINDOWS 
0 


The following example shows how to use SDECWINDOWS in a debugger 
initialization file to position the debugger source window, SRC, at debugger 
startup: 
IF SDECWINDOWS THEN 
! DECwindows (workstation) syntax: 
(DISPLAY SRC AT (100,300,100, 700)) 
ELSE 
! Screen-mode (terminal) syntax: 
(DISPLAY SRC AT (AT H1)) 


D.3.5 Controlling the Input Radix 


The built-in symbols BIN, %DEC, %HEX, and %OCT can be used in address 
expressions and language expressions to specify that an integer literal that 
follows (or all integer literals in a parenthesized expression that follows) should 
be interpreted in binary, decimal, hexadecimal, or octal radix, respectively. Use 
these radix built-in symbols only with integer literals. 

For example: 


DBG> EVALUATE/DEC %HEX 10 
Bes EVALUATE/DEC SHEX (10 + 10) 
nt EVALUATE/DEC %BIN 10 
ies EVALUATE/DEC %OCT (10 + 10) 
DBG> EVALUATE/HEX %DEC 10 


DBG> SET RADIX DECIMAL 
DBG> EVALUATE %HEX 20 + 33 ! Treat 20 as hexadecimal, 33 as decimal 


65 ! Resulting value is decimal 

DBG> EVALUATE %HEX (20+33) ! Treat both 20 and 33 as hexadecimal 
83 

DBG> EVALUATE %HEX (20+ %O0CT 10 +33) ! Treat 20 and 33 as 

91 ! hexadecimal and 10 as octal 


DBG> SYMBOLIZE SHEX 27C9E3 ! Symbolize a hexadecimal address 
DBG> DEPOSIT/INST %SHEX 5432 = 'MOVL *“O%DEC 222, RI’ 
DBG> ! Treat address 5432 as hexadecimal, and operand 222 as decimal 


D.3.6 Specifying Program Locations and the Current Value of an Entity 


The following built-in symbols enable you to specify program locations and the 
current value of an entity. 
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Symbol Description 

%CURLOC Current logical entity—the program location last referenced by an 

. (period) EXAMINE, DEPOSIT, or EVALUATE/ADDRESS command. 

%NEXTLOC Logical successor of the current entity—the program location that 

Return key logically follows the location last referenced by an EXAMINE, 
DEPOSIT, or EVALUATE/ADDRESS command. Because the 
Return key is a command terminator, it can be used only where a 
command terminator is appropriate (for example, immediately after 
EXAMINE, but not immediately after DEPOSIT or EVALUATE 
/ADDRESS). 

%PREVLOC Logical predecessor of current entity—the program location that 

4 (circumflex) logically precedes the location last referenced by an EXAMINE, 

DEPOSIT, or EVALUATE/ADDRESS command. 
%CURVAL Value last displayed by an EVALUATE or EXAMINE command, 
\ (backslash) or deposited by a DEPOSIT command. These two symbols are not 


affected by an EVALUATE/ADDRESS command. 


In the following example, the variable WIDTH is examined; the value 12 is then 
deposited into the current location (WIDTH); this is verified by examining the 
current location: 


DBG> EXAMINE WIDTH 
MOD\WIDTH: 7 

DBG> DEPOSIT . = 12 
DBG> EXAMINE . 
MOD\WIDTH: 12 

DBG> EXAMINE %CURLOC 
MOD\WIDTH: 12 

DBG> 


In the next example, the next and previous locations in an array are examined: 


DBG> EXAMINE PRIMES (4) 
MOD\PRIMES (4): 7 

DBG> EXAMINE %NEXTLOC 
MOD\PRIMES (5): 11 
DBG> EXAMINE ! Examine next location 
MOD\PRIMES (6): 13 

DBG> EXAMINE SPREVLOC 

MOD\PRIMES (5): 11 

DBG> EXAMINE “* 

MOD\PRIMES (4): 7 

DBG> 


Note that using the Return key to signify the logical successor does not apply 

to all contexts. For example, you cannot press the Return key after typing the 
command DEPOSIT to indicate the next location, whereas you can always use the 
symbol %NEXTLOC for that purpose. 


D.3.7 Using Symbols and Operators in Address Expressions 


The symbols and operators that can be used in address expressions are listed 
below. A unary operator has one operand. A binary operator has two operands. 
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Symbol Description 
%LABEL Specifies that the numeric literal that follows is a program 


label (for languages like FORTRAN that have numeric 
program labels). You can qualify the label with a path 
name prefix that specifies the containing module. 


%LINE Specifies that the numeric literal that follows is a line 
number in your program. You can qualify the line number 
with a path name prefix that specifies the containing 
module. 


Backslash ( \ ) When used within a path name, delimits each element of 
the path name. In this context, the backslash cannot be 
the leftmost element of the complete path name. 


When used as the prefix to a symbol, specifies that the 
symbol is to be interpreted as a global symbol. In this 
context, the backslash must be the leftmost element of the 
symbol’s complete path name. 


At sign (@) Unary operators. In an address expression, the at sign 

Period (.) (@) and period (.) each function as a "contents-of" 
operator. The "contents-of" operator causes its operand 
to be interpreted as a memory address and thus requests 
the contents of (or value residing at) that address. 


Bit field <p,s,e> Unary operator. You can apply bit field selection to an 
address-expression. To select a bit field, you supply a bit. 
offset (p), a bit length (s), and a sign extension bit (e), 
which is optional. 


Plus sign (+) Unary or binary operator. As a unary operator, indicates 
the unchanged value of its operand. As a binary operator, 
adds the preceding operand and succeeding operand 
together. 


Minus sign (—) Unary or binary operator. As a unary operator, indicates 
the negation of the value of its operand. As a binary 
operator, subtracts the succeeding operand from the 
preceding operand. 


Multiplication sign (*) Binary operator. Multiplies the preceding operand by the 
succeeding operand. 


Division sign (/) Binary operator. Divides the preceding operand by the 
succeeding operand. 


The following examples illustrate the use of built-in symbols and operators in 
address expressions. 


%LINE and %LABEL Operators 


The following command sets a tracepoint at line 26 of the module in which 
execution is currently suspended: 


DBG> SET TRACE sLINE 26 


The next command displays the source line associated with line 47: 


DBG> EXAMINE/SOURCE SLINE 47 
module MAIN 

47: procedure SWAP(X,Y: in out INTEGER) is 
DBG> 


The next command sets a breakpoint at label 10 of module MOD4: 
DBG> SET BREAK MOD4\%LABEL 10 
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Path Name Operators 


The following command displays the value of the variable COUNT that is 
declared in routine ROUT2 of module MOD4. The backslash (\ ) path name 
delimiter separates the path name elements: 


DBG> EXAMINE MOD4\ROUT2\COUNT 
MOD4\ROUT2\COUNT: 12 
DBG> 


The following command sets a breakpoint on line 26 of the module QUEUMAN: 
DBG> SET BREAK QUEUMAN\%LINE 26 


The following command displays the value of the global symbol X: 
DBG> EXAMINE \X 


Arithmetic Operators 


The order in which the debugger evaluates the elements of an address expression 
is similar to that used by most programming languages. The order is determined 
by the following three factors, listed in decreasing order of precedence (first listed 
have higher precedence): 


1. The use of delimiters (usually parentheses or brackets) to group operands 
with particular operators 


2. The assignment of relative priority to each operator 

3. Left-to-right priority of operators 

The debugger operators are listed in decreasing order of precedence as follows: 
1. Unary operators ((.), (@), (+), (—)) 

2. Multiplication and division operators ((*), (/)) 

3. Addition and subtraction operators ((+), (—)) 


For example, when evaluating the following expression, the debugger first adds 
the operands within parentheses, then divides the result by 4, then subtracts the 
result from 5. 


5—-(T+5)/4 


The following command displays the value contained in the memory location X + 
4 bytes: 


DBG> EXAMINE X + 4 


Contents-of Operator 

The following examples illustrate use of the contents-of operator. In the next 
example, the instruction at the current PC value is obtained (the instruction 
whose address is contained in the PC and which is about to execute): 


DBG> EXAMINE .%PC 
MOD\SLINE 5: PUSHL  S*#8 
DBG> 


In the next example, the source line at the PC value one level down the call stack 
is obtained (at the call to routine SWAP): 


DBG> EXAMINE/SOURCE .1\%PC 
module MAIN 

MAIN\$LINE 134: SWAP (X,Y); 
DBG> 
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For the next example, assume that the value of pointer variable PTR is 7FF00000 
hexadecimal, the address of an entity that you want to examine. Assume further 
that the value of this entity is 3FF00000 hexadecimal. The following command 
shows how to examine the entity: 


DBG> EXAMINE/LONG .PTR 
7FFO0000: 3FF00000 
DBG> 


In the next example, the contents-of operator (at sign or period) is used with the 
current location operator (period) to examine a linked list of three quadword- 
integer pointer variables (identified as L1, L2, and L3 in the illustration that 
follows). P is a pointer to the start of the list. The low longword of each pointer 
variable contains the address of the next variable; the high longword of each 
variable contains its integer value (8, 6, and 12, respectively). 





ZK-7936-GE 


DBG> SET TYPE QUADWORD; SET RADIX HEX 
DBG> EXAMINE .P ! Examine the entity whose address 

! is contained in P. 
00009BC2: 00000008 O0009BDA ! High word has value 8, low word 

! has address of next entity (9BDA). 
DBG> EXAMINE @. ! Examine the entity whose address 

! is contained in the current entity. 
QOOO9BDA: 00000006 OO0009BF4 ! High word has value 6, low word 

! has address of next entity (9BF4). 
DBG> EXAMINE .. ! Examine the entity whose address 

! is contained in the current entity. 
OO0009BF4: 0000000C 00000000 ! High word has value 12 (dec.), low word 

! has address 0 (end of list). 


Bit-Field Operator 

The following example shows how to use the bit-field operator. For example, to 
examine the address expression X_NAME starting at bit 3 with a length of 4 bits 
and no sign extension, you would enter the following command: 


DBG> EXAMINE X_ NAME <3,4,0> 


D.3.8 Obtaining Information About Exceptions 


The following built-in symbols enable you to obtain information about the current 
exception and use that information to qualify breakpoints or tracepoints. 


Symbol Description 
%EXC_FACILITY Name of facility that issued the current exception 
%EXC_NAME Name of current exception 
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Symbol Description 
%ADAEXC_NAME Ada exception name of current exception (for Ada programs only) 
%EXC_NUMBER Number of current exception 


%EXC_SEVERITY Severity code of current exception 


For example: 


DBG> EVALUATE %EXC_NAME 
"PLTDIV F" 
DBG> SET BREAK/EXCEPTION WHEN (%EXC_NAME = "FLTDIV_F") 


DBG> EVALUATE SEXC_NUMBER 

LZ 

DBG> EVALUATE/ CONDITION VALUE EXC NUMBER 

SSYSTEM-F-ACCVIO, access violation at PC !XL, virtual address !XL 
DBG> SET BREAK/EXCEPTION WHEN (SEXC_NUMBER = 12) 


Note that the conditional expressions in the WHEN clauses are language-specific. 


D.3.9 Specifying the Current, Next, and Previous Scope on the Call Stack 
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You can use the following built-in symbols to obtain and manipulate the scope for 
symbol lookup and for source or instruction display relative to the routine call 
stack. 


Built-in Symbol Description 
%CURRENT_SCOPE_ENTRY The call frame that the debugger is currently using 


as reference when displaying source code or decoded 
VAX instructions, or when searching for symbols. By 
default, this is call frame 0. 


%NEXT_SCOPE_ENTRY The next call frame down the call stack from the call 
frame denoted by S7CURRENT_SCOPE_ENTRY. 


%PREVIOUS_SCOPE_ENTRY The next call frame up the call stack from the call 
frame denoted by %CURRENT_SCOPE_ENTRY. 


These symbols return integer values that denote a call frame on the call stack. 
Call frame 0 denotes the routine at the top of the stack, where execution is 
suspended. Call frame 1 denotes the calling routine, and so on. 


For example, the following command specifies that the debugger search for 
symbols starting with the scope denoted by the next routine down the call stack 
(rather than starting with the routine at the top of the call stack): 


DBG> SET SCOPE/CURRENT %NEXT_ SCOPE ENTRY 


E 


Summary of Debugger Support for Languages 


You can use the debugger with the following VAX languages: 


Ada 
BASIC 
BLISS 

C 

COBOL 
DIBOL 
FORTRAN 
MACRO-32 
Pascal 
PL/I 

RPG II 
SCAN 


The debugger recognizes the syntax, data typing, and scoping rules of each 
language. It also recognizes each language’s operators and expression syntax. 
Therefore, when using debugger commands you can specify variables and other 
program entities as you might in the source code of the program. And you can 
compute the value of a source-language expression using the syntax of that 
language. 


Other parts of this manual describe debugging techniques that are common to 
most of the supported languages. This appendix provides additional information 
that is specific to each language: 


¢ Supported operators in language expressions 
¢ Supported constructs in language expressions and address expressions 
¢ Supported data types 


e Any other language-specific information, including restrictions in debugger 
support, if any 


For more information about language-specific debugger support, refer to the 
documentation furnished with a particular language. 


If your program is written in more than one language, you can change the 
debugging context from one language to another during a debugging session. 
To do so, use the SET LANGUAGE command, specifying one of the following 
keywords: 


ADA 
BASIC 
BLISS 
C 
COBOL 
DIBOL 
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FORTRAN 
MACRO-32 
PASCAL 


When debugging a program that is written in an unsupported language, enter 
the SET LANGUAGE UNKNOWN command. To maximize the usability of the 
debugger with unsupported languages, this setting causes the debugger to accept 
a large set of data formats and operators, including some that might be specific 
to only a few supported languages. For information about the operators and 
constructs that are recognized when the language is set to UNKNOWN, see 
Section E.13. 


This section describes debugger support for Ada. For information specific to Ada 
tasking programs, see also Chapter 12. 


E.1.1 Ada Names and Symbols 


The following sections present the debugger support for Ada names and symbols, 
including predefined attributes. . 


Note that parts of names may be language expressions—for example, attributes 
such as FIRST or ’POS. This affects how you use the EXAMINE, EVALUATE, 
and DEPOSIT commands with such names. See the examples of enumeration 
types in Section E.1.1.2.1. - 


E.1.1.1 Ada Names 
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Supported Ada names follow: 


Kind of Name Debugger Support 


Lexical elements Full support for Ada rules for the syntax of identifiers. 


Function designators that are operator symbols (for example, 
+ and *) rather than identifiers must be prefixed with 
%NAME. Also, the operator symbol must be enclosed in 
quotation marks. 


Full support for Ada rules for numeric literals, character 
literals, string literals, and reserved words. 


The debugger accepts signed integer literals in the range 
—2147483648 to 2147483647. 


Depending on context, the debugger interprets floating-point 
types as F_floating, D_floating, G_floating, or H_floating. 


Indexed components Full support. 


Slices You can examine and evaluate an entire slice or an indexed 
component of a slice. 


You can deposit only to an indexed component of a slice. You 
cannot deposit an entire slice. 


Selected components Full support, including use of the keyword all in .all. 


Kind of Name 


Literals 
Boolean symbols 
Aggregates 


E.1.1.2 Predefined Attributes 
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Debugger Support 


Full support, including the keyword null. 
Full support (TRUE, FALSE) 


You can examine the entire record and array objects with 
the EXAMINE command. You can deposit a value in a 
component of an array or record. You cannot use the 
DEPOSIT command with aggregates, except to deposit 
character string values. 


Supported Ada predefined attributes follow. Note that the debugger SHOW 
SYMBOL/TYPE command provides the same information that is provided by the 
P’ FIRST, P’ LAST, P’ LENGTH, P’ SIZE, and P’ CONSTRAINED attributes. 


Attribute 
P’ CONSTRAINED 


P’ FIRST 


P’ FIRST 
P’ FIRST(N) 


P’ LAST 


P’ LAST 

P’ LAST(N) 

P’ LENGTH 

P’ LENGTH(N) 
P’ POS(X) 


P’ PRED(X) 


Debugger Support 


For a prefix P that denotes a record object with discriminants. 
The value of P’ CONSTRAINED reflects the current state of P 
(constrained or unconstrained). 


For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the lower bound of P. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the lower bound of 
the first index range. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the lower bound of 
the Nth index range. 


For a prefix P that denotes an enumeration type, or a subtype of 
an enumeration type. Yields the upper bound of P. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper bound of 
the first index range. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the upper bound of 
the Nth index range. 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of values 
of the first index range (zero for a null range). 


For a prefix P that is appropriate for an array type, or that 
denotes a constrained array subtype. Yields the number of values 
of the Nth index range (zero for a null range). 


For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the position number of the value X. 
The first position is 0. 


For a prefix P that denotes an enumeration type or a subtype 
of an enumeration type. Yields the value of type P which has a 
position number one less than that of X. 
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Attribute Debugger Support 

P’ SIZE : For a prefix P that denotes an object. Yields the number of bits 
allocated to hold the object. 

P’ SUCC(X) For a prefix P that denotes an enumeration type or a subtype 


of an enumeration type. Yields the value of type P which has a 
position number one more than that of X. 


P’ VAL(N) For a prefix P that denotes an enumeration type or a subtype of 
an enumeration type. Yields the value of type P which has the 
position number N. The first position is 0. 


E.1.1.2.1 Specifying Attributes with Enumeration Types Consider the following 
declarations: 


type DAY is 
(MONDAY , TUESDAY , WEDNESDAY , THURSDAY, FRIDAY, SATURDAY, SUNDAY) ; 
MY_DAY : DAY; 


The following examples show the use of attributes with enumeration types. 
Note that you cannot use the EXAMINE command to determine the value 

of attributes, because attributes are not variable names. You must use the 
EVALUATE command instead. For the same reason, attributes can appear only 
on the right of the := operator in a DEPOSIT command. 


DBG> EVALUATE DAY’ FIRST 

MONDAY 

DBG> EVALUATE DAY’ POS (WEDNESDAY) 
2 


DBG> EVALUATE DAY’ VAL (4) 

FRIDAY 

DBG> DEPOSIT MY DAY := TUESDAY 

DBG> EVALUATE DAY’ SUCC (MY_DAY) 

WEDNESDAY 

DBG> DEPOSIT . := DAY’PRED(MY DAY) 

DBG> EXAMINE . 

EXAMPLE.MY DAY: MONDAY 

DBG> EVALUATE DAY’ PRED (MY_DAY) 

SDEBUG-W-ILLENUMVAL, enumeration value out of legal range 


E.1.1.2.2 Resolving Overloaded Enumeration Literals Consider the following 
declarations: 


type MASK is (DEC, FIX,EXP); 
type CODE is (FIX,CLA,DEC); 
MY MASK : MASK; 
MY CODE : CODE; 


In the following example, the qualified expression CODE’ (FIX) resolves the 
overloaded enumeration literal FIX, which belongs to both type CODE and type 
MASK: 


DBG> DEPOSIT MY_CODE := FIX 
SDEBUG-W-NOUNIQUE, symbol ‘FIX’ is not unique 
DBG> SHOW SYMBOL/TYPE FIX 
data EXAMPLE.FIX 
enumeration type. (CODE, 3 elements), size: 1 byte 
data EXAMPLE.FIX 
enumeration type (MASK, 3 elements), size: 1 byte 
DBG> DEPOSIT MY_ CODE := CODE’ (FIX) 
DBG> EXAMINE MY CODE 
EXAMPLE.MY CODE: FIX 
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E.1.2 Operators and Expressions 
The following sections present the debugger support for Ada operators and 


language expressions. 


E.1.2.1 Operators in Language Expressions 
Supported Ada operators in language expressions follow: 


Kind 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 


Symbol 


+ 


MOD 
REM 


eek 


OR 
XOR 


Function 


Unary plus (identity) 

Unary minus (negation) 

Addition 

Subtraction 

Multiplication 

Division 

Modulus 

Remainder 

Exponentiation 

Absolute value 

Concatenation (only string types) 

Equality (only scalar and string types) 
Inequality (only scalar and string types) 
Greater than (only scalar and string types) 
Greater than or equal (only scalar and string types) 
Less than (only scalar and string types) 
Less than or equal (only scalar and string types) 
Logical NOT 

Logical AND (not for bit arrays) 

Logical OR (not for bit arrays) 

Logical exclusive OR (not for bit arrays) 


The debugger does not support the following items: 


¢ Operations on entire arrays or records 


e The short-circuit control forms: and then, or else 


¢ The membership tests: in, not in 


¢ User-defined operators 
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E.1.2.2 Language Expressions 
Supported Ada expressions follow: 


Kind of Expression 


Type conversions 


Subtypes 


Qualified expressions 


Allocators 
Universal expressions 


E.1.3 Data Types 
Supported Ada data types follow: 
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Ada Data Type 


INTEGER 
SHORT_INTEGER 


Debugger Support 


No support for any of the explicit type conversions specified 
in Ada, However, the debugger performs certain implicit type 
conversions between numeric types during the evaluation of 
expressions. 


The debugger converts lower-precision types to higher-precision 
types before evaluating expressions involving types of different 
precision: 


e Ifinteger and floating-point types are mixed, the integer 
type is converted to floating-point type. 


e If integer and fixed-point types are mixed, the integer type 
is converted to fixed-point type. 


e If integer types of different sizes are mixed (for example, 
byte-integer and word-integer), the one with the smaller 
size is converted to the larger size. 


Full support. Note that the debugger denotes subtypes and 
types that have range constraints as “subrange” types. 


Supported as required to resolve overloaded enumeration 
literals (literals that have the same identifier but belong to 
different enumeration types). The debugger does not support 
qualified expressions for any other purpose. 


No support for any operations with allocators. 
No support. 


VAX Data Type Name 


Longword Integer (L) 
Word Integer (W) 


SHORT_SHORT_INTEGER 
SYSTEM.UNSIGNED_QUADWORD 
SYSTEM.UNSIGNED_LONGWORD 
SYSTEM.UNSIGNED_WORD 
SYSTEM.UNSIGNED_BYTE 
FLOAT 

SYSTEM.F_FLOAT 
SYSTEM.D_FLOAT 

LONG_FLOAT 


SYSTEM.G_FLOAT 


Byte Integer (B ) 
Quadword Unsigned (QU) 
Longword Unsigned (LU) 
Word Unsigned (WU) 
Byte Unsigned (BU) 
F_Floating (F) 
F_Floating (F) 
D_Floating (D) 


D_Floating (D), if pragma LONG_FLOAT 
(D_FLOAT) is in effect. G_Floating (G), 
if pragma LONG_FLOAT (G_FLOAT) is in 
effect. 


G_Floating (G) 


Ada Data Type 


SYSTEM.H_FLOAT 
LONG_LONG_FLOAT 
Fixed 

STRING 

BOOLEAN 
BOOLEAN 
Enumeration 


Arrays 

Records 

Access (pointers) 
Tasks 


E.1.4 Compiling and Linking 
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VAX Data Type Name 


H_Floating (H) 
H_Floating (H) 

(None) 

ASCII Text (T) 

Aligned Bit String (V) 
Unaligned Bit String (VU) 


For any enumeration type whose value fits 
into an unsigned byte or word: Byte Unsigned 
(BU) or Word Unsigned (WU), respectively. 
Otherwise: No corresponding VAX data type. 


(None) 
(None) 
(None) 
(None) 


The Ada predefined units in the ADA$PREDEFINED program library on your 
system have been compiled with the /NODEBUG qualifier. Before using the 
debugger to refer to names declared in the predefined units, you must first copy 
the predefined unit source files using the ACS EXTRACT SOURCE command. 
Then, you must compile the copies into the appropriate library with the /DEBUG 
qualifier, and relink the program with the (DEBUG qualifier. 


If you use the /NODEBUG qualifier with one of the Ada compilation commands, 
only global symbol records are included in the modules for debugging. Global 
symbols in this case are names that the program exports to modules in other 
languages by means of the Ada export pragmas: EXPORT_PROCEDURE, 
EXPORT_VALUED_PROCEDURE, EXPORT_FUNCTION, EXPORT_OBJECT, 
EXPORT_EXCEPTION, and PSECT_OBJECT. 


The /DEBUG qualifier on the ACS LINK command causes the linker to include 
all debugging information in the closure of the specified unit in the executable 


image. 


E.1.5 Source Display 


Source code may not be available for display for the following reasons that are 


specific to Ada programs: 


¢ Execution is suspended within Ada initialization or elaboration code, for 


which no source code is available. 


¢ The copied source file is not in the program library where the unit was 


originally compiled. 


¢ The external source file is not where it was when the unit was originally 


compiled. 


¢ The source file has been modified since the executable image was generated, 
and the original copied source file or external source file no longer exists. 


The following paragraphs explain how to control the display of source code with 


Ada programs. 
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If the compiler command’s /COPY_SOURCE qualifier (the default) was in effect 
when you compiled your program, the debugger obtains the displayed Ada 
source code from the copied source files located in the program library where 
the program was originally compiled. If you compiled your program with the 
/NOCOPY_SOURCE qualifier, the debugger obtains the displayed Ada source 
code from the external source files associated with your program’s compilation 
units. 


The file specifications of the copied or external source files are embedded in 

the associated object files. For example, if you have used the ACS COPY UNIT 
command to copy units, or the DCL COPY or BACKUP command to copy an 
entire library, the debugger still searches the original program library for copied 
source files. If, after copying, the original units have been modified or the original 
library has been deleted, the debugger may not find the original copied source 
files. Similarly, if you have moved the external source files to another disk or 
directory, the debugger may not find them. 


In such cases, use the SET SOURCE command to locate the correct files for 
source display. You can specify a search list of one or more program library or 
source code directories. For example (ADA$LIB is the logical name that the 
program library manager equates to the current program library): 


DBG> SET SOURCE ADASLIB, DISK: [SMITH.SHARE.ADALIB] 


The SET SOURCE command does not affect the search list for the external source 
files that the debugger fetches when you use the debugger EDIT command. To 
tell the EDIT command where to look for your source files, use the SET SOURCE 
/EDIT command. 


E.1.6 EDIT Command 
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With Ada programs, by default the debugger EDIT command fetches the external 
source file that was compiled to produce the compilation unit in which execution 
is currently suspended. You do not edit the copied source file, in the program 
library, that the debugger uses for source display. 


The file specifications of the source files you edit. are embedded in the associated 
object files during compilation (unless you specify /NODEBUG). If some source 
files have been relocated after compilation, the debugger may not find them. 


In such cases, you can use the debugger SET SOURCE/EDIT command to specify 
a search list of one or more directories where the debugger should look for source 
files. For example: 


DBG> SET SOURCE/EDIT [],USER: [JONES.PROJ.SOURCES] 


The SET SOURCE/EDIT command does not affect the search list for copied 
source files that the debugger uses for source display. 


The SHOW SOURCE/EDIT command displays the source-file search list currently 
being used for the EDIT command. The CANCEL SOURCE/EDIT command 
cancels the source-file search list currently being used for the EDIT command and 
restores the default search mode. 
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E.1.7 GO and STEP Commands 


Note the following points about using the GO and STEP commands with Ada 
programs: 


¢ When starting a debugging session, use the GO command rather than the 
STEP command to avoid stepping through compiler-generated initialization 
code. 


— Use the GO command to go directly to the preset breakpoint at the start 
of the main program, past the initialization and package elaboration code. 


— Use the GO command and breakpoints to suspend execution at the start 
of the elaboration of library packages, before execution reaches the main 
program. 


Section E.1.8 explains how to monitor the package elaboration phase. 


¢ Ifa line contains more than one statement, a STEP command executes all the 
statements on that line as part of a single step. 


e Ada task entry calls are not the same as subprogram calls because task 
entry calls are queued and may not execute right away. If you use the STEP 
command to move execution into a task entry call, the results might not be 
what you expect. . 


E.1.8 Debugging Ada Library Packages 


When an Ada main program (or a non-Ada main program that calls Ada 

code) is executed, initialization code is executed for the Ada run-time library 
and elaboration code for all library units that the program depends on. The 
elaboration code causes the library units to be elaborated in appropriate order 
before the main program is executed. Library specifications, bodies, and some of 
their subunits are also elaborated by this process. . 


The elaboration of library packages accomplishes the following operations: 
¢ Causes package declarations to take effect 
¢ Initializes any variables whose declaration includes initialization code 


e Executes any sequence of statements that appear between the begin and end 
statements of package bodies 


When you invoke the debugger with an Ada program, execution is suspended 
initially before the initialization code is executed and before the elaboration of 
library units. For example: 


$ RUN FORMS 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is ADA, module set to FORMS 
SDEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 


At that point, before typing GO to get to the start of the main program, you can 
step through and examine parts of the library packages by setting breakpoints at 
the package specifications or bodies you are interested in. You then use the GO 
command to get to the start of each package. To set a breakpoint on a package 
body, specify the package unit name with the SET BREAK command. To set a 
breakpoint on a package specification, specify the package unit name followed by 
a trailing underscore character (_). 
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Even if you have set a breakpoint on a package body, the break will not occur if 
the debugger module for that body is not set. If the module is not set, the break 
will occur at the package specification. This effect occurs because the debugger 
automatically sets modules for the specifications of packages named in with 
clauses; it does not automatically set modules for the associated package bodies 
(see Section E.1.14). 


Also, to set a breakpoint on a subprogram declared in a package specification, you 
must set the module for the package body. 


Note that the compiler generates unique names for subprograms declared in 
library packages that are or could be overloaded names. The debugger uses these 
unique names in its output, and requires them in commands where the names 
would otherwise be ambiguous. For more information on resolving overloaded 
names and symbols, see Section E.1.15. 


E.1.9 Predefined Breakpoints 


When you invoke the debugger with an Ada program (or a non-Ada program 
that calls Ada code), two breakpoints that are associated with Ada tasking 
exception events are automatically established. These breakpoints are established 
automatically during debugger initialization when the Ada Run-Time Library is 
present. 


When you enter a SHOW BREAK command under these conditions, the following 
breakpoints are displayed: 


DBG> SHOW BREAK 

Predefined breakpoint on ADA event "EXCEPTION TERMINATED" for any value 
Predefined breakpoint on ADA event "DEPENDENTS EXCEPTION" for any value 
DBG> 


E.1.10 Monitoring Exceptions 


The debugger recognizes three kinds of exceptions in Ada programs: 


¢ A user-defined exception—an exception declared with the Ada reserved word 
exception in an Ada compilation unit 


e An Ada predefined exception, such as PROGRAM_ERROR or CONSTRAINT_ 
ERROR 


e Any other (non-Ada) exception or VMS condition 


The following sections explain how to monitor such exceptions. 


E.1.10.1 Monitoring Any Exception 
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The SET BREAK/EXCEPTION command enables you to set a breakpoint on 

any exception or VMS condition. This includes certain VMS conditions that are 
signaled internally within the VAX Ada run-time library. These conditions are an 
implementation mechanism—they do not represent program failures, and they 
cannot be handled by Ada exception handlers. If these conditions appear while 
you are debugging your program, you may want to consider specifying the kind of 
exceptions when setting breakpoints (see Section E.1.10.2 and Section E.1.10.3). 


The following example shows a tracepoint occurring for an Ada CONSTRAINT_ 
ERROR exception as the result of a SET TRACE/EXCEPTION debugger 
command: 
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DBG> SET TRACE/EXCEPTION 
DBG> GO 


sADA-F-CONSTRAINT ERRO, CONSTRAINT ERROR 
~ADA-I-EXCRAIPRI, Exception raised prior to PC = O00Q00A7C 
trace on exception preceding ADASRAISE\ADASRAISE CONDITION. %LINE 333+12) 


In the next example, the SHOW CALLS command displays a traceback of the 
calls leading to the subprogram where the exception occurred or to which the 
exception was raised: 


DBG> SET BREAK/EXCEPTION DO (SHOW CALLS) 
DBG> GO 


SSYSTEM-F-INTDIV, arithmetic trap, integer divide by zero at PC=000008AF, 
PSL=03C000A2 break on exception preceding SYSTEM OPS.DIVIDE.%LINE 17+6 


Lys return X/Y; 
module name routine name line rel PC abs PC 
*SYSTEM OPS DIVIDE 17 =©00000015 Q00008AF 
*PROCESSOR PROCESSOR 19  QOO000AE O0000BAD 
*ADASELAB PROCESSOR 
ADASELAB_PROCESSOR 00000009 00000809 
LIBSINITIALIZE 00000054 00000C36 
SHARESADARTL 00000000 000398BE 
*ADASELAB_ PROCESSOR 
ADASELAB_ PROCESSOR 0000001B 00000818 
LIBSINITIALIZE 0000002F 00000C21 


In this example, the VAX condition SS$_INTDIV is raised at line 17 of the 
subprogram DIVIDE in the package SYSTEM_OPS. The example shows an 
important effect: some VAX conditions (such as $SS_INTDIV) are treated as 
being equivalent to some Ada predefined exceptions. 


The matching of a VAX condition and an Ada predefined exception is performed 
by the condition handler provided by VAX Ada for any frame that includes 

an exception part. Therefore, when an exception breakpoint or tracepoint is 
triggered by a VAX condition that has an equivalent Ada exception name, the 
message displays only the system condition code name, and not the name of the 
corresponding Ada exception. 


E.1.10.2 Monitoring Specific Exceptions 
Whenever an exception is raised, the debugger sets the following built-in symbols. 
You can use them to qualify exception breakpoints or tracepoints so that they 
trigger only on certain exceptions. 


%EXC_FACILITY A string that names the facility that issued the exception. The 
facility name for Ada predefined exceptions and user-defined 


exceptions is ADA. 
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%EXC_NAME An uppercase string that names the exception. If the exception 
' raised is an Ada predefined exception, its name is truncated 
if it exceeds 15 characters. For example, CONSTRAINT_ 
ERROR is truncated to CONSTRAINT_ERRO. If the exception 
is a user-defined exception, %EXC_NAME contains the string 
"EXCEPTION", and the name of the user-defined exception is 
contained in %ADAEXC _NAME. 


%ADAEXC_NAME If the exception raised is user-defined, Z7ADAEXC_NAME contains 
a string that names the exception, and %EXC_NAME contains 
the string "EXCEPTION". If the exception is not user-defined, 
%ADAEXC_NAME contains a null string, and the name of the 
exception is contained in %EXC_NAME. 


%EXC_NUM The number of the exception. — 
%EXC_SEVERITY A string that gives the exception severity level (F, E, W, I, S, or ?). 


E.1.10.3 | Monitoring Handled Exceptions and Exception Handlers 
The SET BREAK/EVENT and SET TRACE/EVENT commands enable you to set 
breakpoints and tracepoints on exceptions that are about to be handled by Ada 
exception handlers. These commands allow you to observe the execution of each 
Ada exception handler that gains control. 


You can specify two event names with these commands—HANDLED and 
HANDLED_OTHERS: 


HANDLED Triggers when an exception is about to be handled in some Ada 
exception handler, including an others handler. 


HANDLED_OTHERS Triggers only when an exception is about to be handled in an 
others Ada exception handler. 


For example, the following command sets a breakpoint that triggers whenever an 
exception is about to be handled by an Ada exception handler: 


DBG> SET BREAK/EVENT=HANDLED 


When the breakpoint triggers, the debugger identifies the exception that is about 
to be handled and the exception handler that is about to be executed. You can 
then use that information to set a breakpoint on a particular handler, or you can 
enter the GO command, and see which Ada handler next attempts to handle the 
exception. For example: 


DBG> GO 


break on Ada event HANDLED 
task STASK 1 is about to handle an exception 
The Ada exception handler is at: PROCESSOR.%LINE 21 
SADA-F-CONSTRAINT ERRO, CONSTRAINT ERROR 
-ADA-I-EXCRAIPRI, Exception raised prior to PC = 00000A7C 
DBG> SET BREAK PROCESSOR.SLINE 21; GO 


E.1.11 Examining and Manipulating Data 
When examining and manipulating data, note the following considerations: 


¢ Before you can examine or deposit into a nonstatic variable (any variable not 
declared in a library package), its defining subprogram, task, and so on, must 
be active on the call stack. 


E-12 


Summary of Debugger Support for Languages 
E.1 Ada 


Before you can examine, deposit, or evaluate an Ada subprogram formal 
parameter or an Ada variable, the parameter or variable must be elaborated. 
In other words, you should step or otherwise move execution past the 
parameter or variable’s declaration. The value contained in any variable or 
formal parameter whose declaration has not been elaborated might be invalid. 


In most cases, the debugger enables you to specify variables and expressions 
in debugger commands exactly as you would specify them in the source code 
of the program, including use of qualified expressions.. (See Section E.1.1 and 
Section E.1.2.) The following sections discuss some additional points about 
debugger support for records and access types. 


E.1.11.1 Records 


Note the following points about debugger support for records: 


With certain Ada record variables, the debugger fails to show the record 
components correctly (possibly with a NOACCESSR error message) when the 
type declaration is in a different scope than the record (symbol) declaration. 


With variant records, the debugger lets you examine or assign a value to 

a component of a variant part that is not active. But because this is an 
illegal action in Ada, the debugger also issues an informational message. For 
example, assume that record REC1 has a variant field named STATUS and 
that the value of STATUS is such that REC1.COMP3 is inactive: 


DBG> EXAMINE REC1.COMP3 

S$DEBUG-I-BADDISCVAL, incorrect value of 1 in discriminant 
field STATUS 

MAIN.REC1.COMP3: 438 


E.1.11.2 Access Types 
Note the following points about debugger. support for access types: 


The debugger does not support allocators, so you cannot create new access 
objects with the debugger. 


When you specify the name of an access object with the EXAMINE command, 
the debugger displays the memory location of the object it designates. 


To examine the value of a designated object, you must use selected component 
notation, specifying .ALL. For example, to examine the value of a record 
access object designated by A: 


DBG> EXAMINE A.ALL 
EXAMPLE.A.ALL 


NAME (1..10): "John Doe " 
AGE : 6 
NEXT: 1462808 


To examine one component of a designated object, you can omit .ALL from the 
selected component syntax. For example: 


DBG> EXAMINE A.NAME 


’ EXAMPLE.A.ALL.NAME(1..10): "John Doe " 


The following example shows the debugger support for incomplete types. 


Consider the following declarations. 
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package P is 

type T is private; 
private 

type T TYPE; 

type T is access T TYPE; 
end P; 7 


package body P is 
type T TYPE is 


record 
A: NATURAL := 5; 
B: NATURAL := 4; 
end record; 
T REC: T TYPE; 
T PTR: T := new T TYPE! (T REC); 


end P; 


with P; use P; 

procedure INCOMPLETE is 
VAR: T; 

begin 


end INCOMPLETE; 


The debugger does not have complete information about the type T, so you cannot 
manipulate the variable VAR. However, the debugger does have information about 
objects declared in the package body P. Thus, you can manipulate the variables 
T_PTR and T_REC. 


E.1.12 Module Names and Path Names 
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The names of Ada debugger modules are the same as the names of the 
corresponding compilation units, with the following provision. To eliminate 
ambiguity, an underscore character (_) is appended to a specification name 
to distinguish it from its body name. For example, TEST (body), TEST_ 
(specification). To determine the exact names of the modules in your program, 
use the SHOW MODULE command. 


When specifying path names, in most cases you do not have to type the trailing 
underscore character to distinguish a specification from its body. The debugger 
can usually distinguish the two from the context. Therefore, use this naming 
convention only if needed to resolve an ambiguity. 


When the debugger language is set to Ada, the debugger generally constructs 
path names that follow the Ada rules, using selected component notation to 
separate path name elements (with other languages, a backslash is used to 
separate elements). For example: 


TEST .A1 ! Al is declared in the package specification of unit TEST 
TEST.B1 ! Bl is declared in the package body of unit TEST 


The maximum length that you can specify for a subunit path name (expanded 
name) is 247 characters. 


When a use clause makes a symbol declared in a package directly visible outside 
the package, you do not need to specify an expanded name (package-name.symbol) 
to refer to the symbol, either in the program itself or in debugger commands. 


The SHOW SYMBOL/USE_CLAUSE command identifies any package (library 
or otherwise) that a specified block, subprogram, or package mentions in a use 
clause. If the entity specified is a package (library or otherwise), the command 
also identifies any block, subprogram, package, and so on, that names the 
specified module in a use clause. For example: 
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DBG> SHOW SYMBOL/USE_CLAUSE B 
package spec B_ 7 7 
used by: F 
uses: AL 


If a label has been assigned to a loop statement or declare block in the source 
code, the debugger displays the label; otherwise, the debugger displays LOOP$n 
for a loop statement or BLOCK$n for a declare block, where n is the line 
number at which the statement or block begins. 


E.1.13 Symbol Lookup Conventions 


For Ada programs, when you do not specify a path name (including an Ada 
expanded name), the debugger searches the Run-Time Symbol Table as follows. 


1. The debugger looks for the symbol within the module (compilation unit) 
surrounding the current PC value (where execution is currently suspended). 


2. Ifthe symbol is not found, the debugger then searches any package that 
is mentioned in a use clause. The debugger does not distinguish between 
a library package and a package whose declaration is in the same module 
as the current scope region. If the same symbol is declared in two or more 
packages that are visible, the symbol is not unique (according to Ada rules), 
and the debugger issues a message like the following: 


%DEBUG-E-NOUNIQUE, symbol 'X’ is not unique 


3. Ifthe symbol is still not found, the debugger searches the call stack and other 
scopes, as for other languages. 


E.1.14 Setting Modules 


When you or the debugger sets an Ada module, by default the debugger also 
sets any “related” module—that is, any module whose symbols should be visible 
within the module being set. Such modules are related to the one being set 
through either a with clause or a subunit relationship. 


Related module setting takes place as follows. If M1 is the module that is being 
set, then the following modules are considered related and are also set: 


e If M1 is a library body, the debugger also sets the associated library 
specification, if any. 


e If M1 is a subunit, the debugger also sets its parent unit and, therefore, any 
parent of the parent. 


e If M1 mentions a library package P1 in a with clause, the debugger also sets 
P1’s specification. Neither the body of P1 nor any possible subunits of Pl are 
set, because symbols declared within them should not be visible outside. 


If P1’s specification mentions a package P2 in a with clause, the debugger 
also sets P2’s specification. Likewise, if P2’s specification mentions a package 
P3 in a with clause, the debugger also sets P3’s specification, and so on. The 
specifications of all such library packages are set so that you can access data 
components (for example, record components) that may have been declared in 
other packages. 


e If M1 mentions a library subprogram in a with clause, the debugger does 
not set the subprogram. Only the subprogram name needs to be visible in 
M1 (no declaration within a library subprogram should be visible outside 
the subprogram). Therefore, the debugger inserts the name of the library 
subprogram into the RST when M1 is set. 
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If debugger performance becomes a problem as more modules are set, use the 
command SET MODE NODYNAMIC, which disables related module setting as 
well as dynamic module setting. You must then set individual modules explicitly 
with the SET MODULE command. 


By default, the SET MODULE command sets related modules simultaneously 
with the module specified in the command. 


SET MODULE/NORELATED sets only the modules you specify explicitly. 
However, if you use SET MODULE/NORELATED, you may find that a symbol 
which is declared in another unit and which should be visible at the point of 
execution is no longer visible; or that a symbol which should be hidden by a 
redeclaration of that same symbol is now visible. 


The CANCEL MODULE/NORELATED command deletes from the RST only the 
modules you specify explicitly. The CANCEL MODULE/RELATED command, 
which is the default, deletes related modules in a manner consistent with the 
intent of Ada’s scope and visibility rules. The exact effect depends on module 
relationships. 


For example, consider the following Ada code: 


P1_ is a library package specification, and P1 is its body. The specification P1_ 
mentions the library package specification P3_ in a with clause. Then: 


¢ CANCEL MODULE/RELATED P3_ deletes only P3_. 


¢ CANCEL MODULE/RELATED P1_ deletes P1_ and P3_ (but P3_ is not 
deleted if it is directly related to another set module). 


* CANCEL MODULE/RELATED P1 deletes P1, P1_, and P3_ (but neither 
P1_ nor P3_ is deleted if either one is directly related to another set module). 


Similarly, consider the following set of subunits: 
P4.SUB1.SUB2 is a subunit of P4.SUB1, which is a subunit of P4. Then: 
¢ CANCEL MODULE/RELATED P4.SUB1.SUB2 deletes P4.SUB1.SUB2. 


¢ CANCEL MODULE/RELATED P4.SUB1 deletes P4.SUB1 and 
P4.SUB1.SUB2. 


¢ CANCEL MODULE/RELATED P4 deletes P4, P4.SUB1, and P4.SUB1.SUB2. 


E.1.14.1 Identifying Related Modules 
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The debugger SHOW MODULE/RELATED command identifies the modules that 
are related to a specified module as defined in Section E.1.14. . The command 
shows the modules that are automatically set when a given module is set. The 
SHOW MODULE/RELATED command also shows the modules that may be 
affected when you enter the CANCEL MODULE command. 


P1_ and P2_ are considered directly related to P1. P3_ is considered related to P1 
(by way of P1_). 


The SHOW MODULE/RELATED command, applied to package body P1, would 
display information like the following: 
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DBG> SHOW MODULE/RELATED Pl 
module name symbols size relationship 
Pl yes 868 
directly related modules: 

BA yes 884 withed 

P2_ yes 916 withed 
related modules: 

Poi. yes 868 withed 
total ADA modules: 1. bytes allocated: 109512. 


The entries in the relationship column indicate that all modules directly related 
and those related to P1 are library packages. Note that the debugger treats the 
relationship between a package body and its specification the same as it treats 
the relationship between a unit and a package it mentions in a with clause. 


Consider the following subunit structure: 
¢ P4 and P4_ are a library package body and its specification, respectively. 
¢ P4.SUB1.SUB2 is a subunit of P4.SUB1, which is a subunit of P4. 


The SHOW MODULE/RELATED command, applied to P4.SUB1, would display 
information like the following: 


DBG> SHOW MODULE/RELATED P4.SUB1° 


module name symbols size relationship 
P4.SUB1 yes 828 
directly related modules: 
P4 yes 776 parent 
P4,SUB1.SUB2 yes 836 subunit 
related modules: 
P4 yes 728 withed 
total ADA modules: 1. bytes allocated: 191888. 


The distinction between related and directly related for subunits is analogous to 
that for library packages. 


E.1.14.2 Setting Modules for Package Bodies 
Modules for package bodies are not automatically set by the debugger. 


You may need to set the modules for library package bodies yourself so that you 
can debug the package body or debug subprograms declared in the corresponding 
package specification. 


For more information on debugging Ada library packages, see Section E.1.8. 


E.1.15 Resolving Overloaded Names and Symbols 


When you encounter overloaded names and symbols, the debugger issues a 
message like the following: 


SDEBUG-E-NOTUNQOVR, symbol ‘ADD’ is overloaded 
use SHOW SYMBOL to find the unique symbol names 


If the overloaded symbol is an enumeration literal, you can use qualified 
expressions to resolve the overloadings. For an example of using qualified 
expressions, see Section E.1.1.2.2. 


If the overloaded symbol represents a subprogram or task accept statement, 
you can use the unique name generated by the compiler for the debugger. The 
compiler always generates unique names for subprograms declared in library 
package specifications, because the names might later be overloaded in the 
package body. Unique names are generated for task accept statements and 
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subprograms declared in other places only if the task accept statements or 
subprograms are actually overloaded. 


Overloaded task accept statement names and subprogram names are 
distinguished by a suffix consisting of two underscores followed by an integer 
that uniquely identifies the given symbol. You must use the unique naming 
notation in debugger commands to uniquely specify a subprogram whose name is 
overloaded. However, if there is no ambiguity, you do not need to use the unique 
name, even though one was generated. 


For example, suppose you are debugging a library package that contains two 
declarations of a subprogram named SQUARES. One returns an integer type, the 
other a float type. If you try to set a breakpoint specifying the name SQUARE, 
you will receive an error like the following: 

DBG> SET BREAK SQUARE 


SDEBUG-E-NOTUNQOVR, symbol ’SQUARE’ is overloaded 
use SHOW SYMBOL to find the unique symbol names 


Proceed as follows to resolve the ambiguity: 


1. Use the SHOW SYMBOL command to identify the overloaded symbols. For 
example: 


DBG> SHOW SYMBOL SQUARE 

overloaded symbol SYSTEM OPS.SQUARE 
overloaded instance SYSTEM OPS.SQUARE_ 1 
overloaded instance SYSTEM OPS.SQUARE 2 


2. Use the EXAMINE/SOURCE command to determine which declaration an 
overloaded subprogram suffix number corresponds to. For example: 
DBG> EXAMINE/SOURCE SQUARE 1, SQUARE 2 
module SYSTEM OPS 
20: function SQUARE (X: INTEGER) return INTEGER is 
module SYSTEM OPS 
29% function SQUARE (X: FLOAT) return FLOAT is 
3. You can then uniquely specify a particular declaration of an overloaded name. 
For example: 


DBG> SET BREAK SYSTEM OPS.ADD 1, SQUARE 2 


E.1.16 CALL Command 
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With Ada programs, you can use the CALL command reliably only with a 
subprogram that has been exported. An exported subprogram must be a library 
subprogram or must be declared in the outermost declarative part of a library 
package. 


The CALL command does not check whether or not the subprogram can be 
exported, nor does it check the parameter-passing mechanisms that you specify. 
Note that you cannot use the CALL command to modify the value of a parameter. 


A CALL command may result in a deadlock if it is entered when the VAX Ada 
run-time library is executing. The VAX Ada run-time library routines acquire and 
release internal locks that allow the routines to operate in a tasking environment. 
Deadlock can result if a subprogram called from the CALL command requires a 
resource that has been locked by an executing VAX Ada run-time library routine. 
To avoid this situation in a nontasking program, enter the CALL command 
immediately before or after an Ada statement has been executed. However, this 
approach is not sufficient to assure that deadlock will not occur in a tasking 
program, as some other task may be executing a VAX Ada run-time library 
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routine at the time of the call. If you must use the CALL command in a tasking 
program, you can avoid deadlock if the called subprogram does not do any tasking 
or input-output operations. 


E.2 BASIC 


This section describes debugger support for BASIC. 


E.2.1 Operators in Language Expressions 
Supported BASIC operators in language expressions follow: 


Kind 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 


Symbol 


XOR 
IMP 
EQV 


Function 


Unary plus 

Unary minus (negation) 
Addition, String concatenation 
Subtraction 
Multiplication 

Division 

Exponentiation 
Exponentiation 

Equal to 

Not equal to 

Not equal to 

Greater than 

Greater than or equal to 
Greater than or equal to 
Less than 

Less than or equal to 
Less than or equal to 
Bit-wise NOT 

Bit-wise AND 

Bit-wise OR 

Bit-wise exclusive OR 
Bit-wise implication 


Bit-wise equivalence 


E.2.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for BASIC follow: 


Symbol 


() 


Construct 


Subscripting 


Record component selection 
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E.2.3 Data Types 
Supported BASIC data types follow: 


BASIC Data Type VAX Data Type Name 
BYTE Byte Integer (B) 
WORD Word Integer (W) 
LONG Longword Integer (L) 
SINGLE F_Floating (F ) 
DOUBLE D_Floating (D) 
GFLOAT G_Floating (G) 
HFLOAT H_Floating (H) 
DECIMAL Packed Decimal (P ) 
STRING ASCII Text (T) 

RFA (None) 

RECORD (None) 

Arrays (None) 


E.2.4 Compiling for Debugging 


If you make changes to a program in the VAX BASIC environment and attempt to 
compile the program with the /DEBUG qualifier without first saving or replacing 
the program, VAX BASIC signals the error “Unsaved changes, no source line 
debugging available.” To avoid this problem, save or replace the program, and 
then recompile the program with the /DEBUG qualifier. 


E.2.5 Constants 


BASIC constants of the forms [radix]‘numeric-string”’[type] (such as 
“12.34”GFLOAT) or n% (such as 25% for integer 25) are not supported in 
debugger expressions. 


E.2.6 Evaluating Expressions 


Expressions that overflow in the BASIC language do not necessarily overflow 
when evaluated by the debugger. The debugger tries to compute a numerically 
correct result, even when the BASIC rules call for overflows. This difference is 
particularly likely to affect DECIMAL computations. 


E.2.7 Line Numbers 


The sequential line numbers that you refer to in a debugging session and that 
are displayed in a source code display are those generated by the compiler. When 
a VAX BASIC program includes or appends code from another file, the included 
lines of code are also numbered in sequence by the compiler. 


E.2.8 Stepping into Routines 


The STEP/INTO command is useful for examining external functions. However, 
if you use this command to stop execution at an internal subroutine or a DEF, 
the debugger initially steps into Run-Time Library (RTL) routines, providing you 
with no useful information. In the following example, execution is suspended at 
line 8, at a call to Print_routine: 
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-> 8 GOSUB Print_routine 
9 STOP 


20 Print _routine: 
21 IF Competition = Done 


22 THEN PRINT "The winning ticket is #";Winning ticket 
23 ELSE PRINT "The game goes on." 

24 END IF 

25 RETURN 


A STEP/INTO command would cause the debugger to step into the relevant RTL 
code and would inform you that no source lines are available for display. On the 
other hand, a STEP command alone would cause the debugger to proceed directly 
to source line 9, past the call to Print_routine. To examine the source code of 
subroutines or DEF functions, set a breakpoint on the routine label (for example, 
enter the command SET BREAK Print_routine). You can then suspend execution 
exactly at the start of the routine (line 20, in this example) and then step directly 
into the code. 


E.2.9 Symbolic References 


All variable and label names within a single VAX BASIC program must be 
unique. Otherwise the debugger cannot resolve the symbol ambiguity. 


E.2.10 Watchpoints 


In VAX BASIC, you can set a watchpoint only on variables that are declared in 
COMMON or MAP statements (static variables). You cannot set watchpoints on 
variables explicitly declared with the DECLARE statement. 


E.3 BLISS 
This section describes debugger support for BLISS. 


E.3.1 Operators in Language Expressions 
Supported BLISS operators in language expressions follow: 


Kind Symbol Function 
Prefix ‘ Indirection 
Prefix + Unary plus 
Prefix - Unary minus (negation) 
Infix + Addition 

Infix - Subtraction 
Infix * Multiplication 
Infix / Division 

Infix MOD Remainder 
Infix an Left shift 
Infix EQL Equal to 

Infix EQLU Equal to 
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Kind Symbol Function 

Infix EQLA Equal to 

Infix NEQ Not equal to 

Infix NEQU Not equal to 

Infix NEQA Not equal to 

Infix GTR Greater than 

Infix GTRU Greater than unsigned 

Infix GTRA Greater than unsigned 

Infix GEQ Greater than or equal to 

Infix GEQU Greater than or equal to unsigned 
Infix GEQA Greater than or equal to unsigned 
Infix LSS Less than 

Infix LSSU Less than unsigned 

Infix LSSA Less than unsigned 

Infix LEQ Less than or equal to 

Infix LEQU Less than or equal to unsigned 
Infix LEQA Less than or equal to unsigned 
Prefix NOT Bit-wise NOT 

Infix AND Bit-wise AND 

Infix OR Bit-wise OR 

Infix XOR Bit-wise exclusive OR 

Infix EQV Bit-wise equivalence 


E.3.2 Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for BLISS follow: 


Symbol Construct | 

LJ Subscripting 
[fidname] Field selection 
<p,s,e> Bit field selection 


E.3.3 Data Types 
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Supported BLISS data types follow: 


BLISS Data Type VAX Data Type Name 
BYTE Byte Integer (B ) 

WORD Word Integer ( W ) 

LONG Longword Integer (L) 
BYTE UNSIGNED Byte Unsigned (BU ) 
WORD UNSIGNED Word Unsigned (WU ) 
LONG UNSIGNED Longword Unsigned (LU) 


BLISS Data Type 


VECTOR 
BITVECTOR 
BLOCK 


BLOCKVECTOR 
REF VECTOR 
REF BITVECTOR 


REF BLOCK 


REF BLOCKVECTOR 
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VAX Data Type Name 


(None) 
(None) 
(None) 
(None) 
(None) 
(None) 
(None) 
(None) 


This section describes debugger support for C. 


E.4.1 Operators in Language Expressions 
Supported C operators in language expressions follow: 


Kind 
Prefix 
Prefix 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 


Symbol 
* 
& 


sizeof 


~ (tilde) 
& 
| 


A 
! 
&& 
1 | 


Function 

Indirection 

Address of 

size of 

Unary minus (negation) 
Addition 

Subtraction 
Multiplication 
Division 

Remainder 

Left shift 

Right shift 

Equal to 

Not equal to 

Greater than 

Greater than or equal to 
Less than 

Less than or equal to 
Bit-wise NOT 
Bit-wise AND 
Bit-wise OR 

Bit-wise exclusive OR 
Logical NOT 

Logical AND 

Logical OR 
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Since the exclamation point (!) is an operator in C, it cannot be used as the 
comment delimiter. When the language is set to C, the debugger instead accepts 
/* as the comment delimiter. The comment continues to the end of the current 
line. (A matching */ is neither needed nor recognized.) To permit debugger log 
files to be used as debugger input, the debugger still recognizes ! as a comment 
delimiter if it is the first nonspace character on a line. 


The debugger accepts the prefix asterisk (*) as an indirection operator in both C 
language expressions and debugger address expressions. In address expressions, 
prefix “*” is synonymous to prefix “.” or “@” when the language is set to C. 


The debugger does not support any of the assignment operators in C (or any other 
language) in order to prevent unintended modifications to the program being 
debugged. Hence such operators as =, +=, —=, ++, and —— are not recognized. To 
alter the contents of a memory location, you must do so with an explicit DEPOSIT 
command. 


E.4.2 Constructs in Language and Address Expressions 


Supported constructs in language and address expressions for C follow: 


Symbol Construct 


[] Subscripting 


Structure component selection 


-> Pointer dereferencing 


E.4.3 Data Types 


Supported C data types follow: 


C Data Type VAX Data Type Name 
int Longword Integer (L) 
unsigned int Longword Unsigned (LU ) 
short int Word Integer (W ) 
unsigned short int Word Unsigned (WU ) 
char Byte Integer (B) 
unsigned char Byte Unsigned (BU ) 
float F_Floating (F) 

double D_Floating (D) 

enum (None) 

struct (None) 

union (None) 

Pointer Type (None) 

Array Type (None) 


E.4.4 Case Sensitivity 
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Symbol names are case sensitive for language C, meaning that uppercase and 
lowercase letters are treated as different characters. 
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E.4.5 Static and Nonstatic Variables 


Variables of the following storage classes are allocated statically: static, globaldef, 
globalref, and extern. 


Variables of the following storage classes are allocated nonstatically (on the stack 
or in registers): auto and register. Such variables can be accessed only when 
their defining routine is active (on the call stack). 


E.4.6 Scalar Variables 


You can specify scalar variables of any C type in debugger commands exactly as 
you would specify them ‘in the source code of the program. 


The following paragraphs provide additional information about char variables 
and pointers. 


The char variables are interpreted by the debugger as byte integers, not ASCII 
characters. To display the contents of a char variable ch as a character, you must 
use the /ASCII qualifier: 


DBG> EXAMINE/ASCII ch 
SCALARS \main\ch: ean 


You also must use the /ASCII qualifier when depositing into a char variable, to 
translate the byte integer into its ASCII equivalent: 
DBG> DEPOSIT/ASCII ch = '2’ 


DBG> EXAMINE/ASCII ch 
SCALARS \main\ch: As 


The following example shows use of pointer syntax with the EXAMINE command. 
Assume the following declarations and assignments: 


790374270; 
&li; 


static long li- 
static int *ptr 


DBG> EXAMINE *ptr 
*SCALARS\main\ptr: 790374270 


E.4.7 Arrays 


The debugger handles C arrays as for most other languages. That is, you can 
examine an entire array aggregate, a slice of an array, or an individual array 
element, using array syntax (for example EXAMINE arr[3]). And you can deposit 
into only one array element at a time. 


E.4.8 Character Strings 


Character strings are implemented in C as null-terminated ASCII strings (ASCIZ 
strings). To examine and deposit data in an entire string, use the /ASCIZ 
qualifier (abbreviated /AZ) so that the debugger can interpret the end of the 
string properly. You can examine and deposit individual characters in the string 
using the C array subscripting operators ({ ]). When you examine and deposit 
individual characters, use the /ASCII qualifier. 


Assume the following declarations and assignments: 


static char *s = "vaxie"; 
static char **t = &s; 


E-25 


Summary of Debugger Support for Languages 


E.4C 


The EXAMINE/AZ command displays the contents of the character string pointed 
to by *s and **t: 


DBG> EXAMINE/AZ *s 
*STRING\main\s: "vaxie" 

DBG> EXAMINE/AZ **t 
**STRING\main\t: "vaxie" 


The DEPOSIT/AZ command deposits a new ASCIZ string in the variable pointed 
to by *s. The EXAMINE/AZ command displays the new contents of the string: 


DBG> DEPOSIT/AZ *s = "VAX C" 
DBG> EXAMINE/AZ *s, **t 
*STRING\main\s: "VAX Cc" 
**STRING\main\t: "VAX C" 


You can use array subscripting to examine individual characters in the string 
and deposit new ASCII values at specific locations within the string. When 
accessing individual members of a string, use the /ASCII qualifier. A subsequent 
EXAMINE/AZ command shows the entire string containing the deposited value: 


DBG> EXAMINE/ASCII s{3] 

[3]: won 

DBG> DEPOSIT/ASCII s[{3] = "-" 
DBG> EXAMINE/AZ *s, **t 
*STRING\main\s: | "VAX-C" 
**STRING\main\t: "VAX-C" 


E.4.9 Structures and Unions 
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You can examine structures in their entirety or on a member-by-member basis, 
and deposit data into structures one member at a time. 


To reference members of a structure or union, use the usual C syntax for such 
references. That is, if variable p is a pointer to a structure, you can reference 
member y of that structure with the expression p ->y. If variable x refers to the 
base of the storage allocated for a structure, you can refer to a member of that 
structure with the x.y expression. 


The debugger uses the C type-checking rules that follow to reference members of 
a structure or union. For example, in the case of x.y, y need not be a member of 
x; it is treated as an offset with a type. When such a reference is ambiguous— 
when there is more than one structure with a member y—the debugger attempts 
to resolve the reference according to the rules that follow. The same rules for 
resolving the ambiguity of a reference to a member of a structure or union apply 
to both x.y and p ->y. | . 


e¢ If only one of the members, y, belongs in the structure or union, x, that is the 
one that is referenced. : 


¢ If only one of the members, y, is in the same scope as x, then that is the one 
that is referenced. | 


You can always give a path name with the reference to x to narrow the scope that 
is used and to resolve the ambiguity. The same path name is used to look up both 
x and y. 


The following example, which defines a structure and union, is used to show how 
to access structures and unions and their elements: 
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main () 
{ 
static struct 
{ 
int im; 
float fm; 
char cm; 
unsigned bf : 3; 
} sv, *p;} 


union 
int im; 
float fm; 
char cm; 


n 
< 
Q 
3 
tououw ou 
ry 
~ 


7; /* Binary: 111 */ 


} 


The SHOW SYMBOL command shows the variables contained in the function 
main: 


DBG> SHOW SYMBOL * in main 

routine STRUCT\main 

data STRUCT\main\uv 

record component STRUCT\main\<generated_name_0002>.im 
record component STRUCT\main\<generated name 0002>.fm 
record component STRUCT\main\<generated_name_0002>.cm 
type STRUCT\main\<generated_name_0002> 

data STRUCT\main\p 

data STRUCT\main\sv 

record component STRUCT\main\<generated name 0001>.im 
record component STRUCT\main\<generated_ name 0001>.fm 
record component STRUCT\main\<generated_name_0001>.cm 
record component STRUCT\main\<generated_name_ 0001>.bf 
type STRUCT\main\<generated_name 0001> 


Use the EXAMINE command with the name of the structure to display all 
structure members. Note that sv.cm has the char data type, which is interpreted 
by the debugger as a byte integer. The debugger also displays the value of bit 
fields in decimal: 


DBG> EXAMINE sv 
STRUCT\main\sv 
im: -24 
fm: 3.0000001E+10 
cm: 97 
bf: 7 


To display the ASCII representation of a char data type, use the /ASCII qualifier 
on the EXAMINE command. To display bit fields in their binary representation, 
use the /BINARY qualifier: 


DBG> EXAMINE/ASCII sv.cm 


STRUCT\main\sv.cm: fan 
DBG> EXAMINE/BINARY sv.bf 
STRUCT\main\sv.bf: 111 
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You deposit data into a structure one member at a time. To deposit data into a 
member of type char, use the /ASCII qualifier and enclose the character in either 
single or double quotation marks. To deposit a new binary value in a bit field, use 
the %BIN keyword: 


DBG> DEPOSIT sv.im 99 
DBG> DEPOSIT sv.fm = 3.14 
DBG> DEPOSIT/ASCII sv.cm = '2z’ 
DBG> DEPOSIT sv.bf = %BIN 010 
DBG> EXAMINE sv 
STRUCT\main\sv 

im: 99 

fm: 3.140000 

em: 122 

bf: 2 


Members of structures (and unions) can also be accessed by pointer, as shown in 
*p and p ->bf: 


DBG> EXAMINE *p 
*STRUCT\main\p 

im: 99 

fm: 3.140000 

em: 122 

bf: 2 
DBG> EXAMINE/BINARY p ->bf 
STRUCT\main\p ->bf: 010 


A union contains only one member at a time, so the value for uv.im is the 
only valid value returned by the EXAMINE command; the other values are 
meaningless: 


DBG> STEP 

stepped to STRUCT\main\%LINE 30 
30: uv.fm = 3.0e10; 

DBG> EXAMINE uv 


STRUCT\main\uv 
im: -24 
fm: -1.5485505E+38 
em: -24 


This series of STEP and EXAMINE commands shows the content of the union as 
the different members are assigned values: 


DBG> STEP 
stepped to STRUCT\main\%LINE 31 
31: uv.cm = ‘a’; 
DBG> EXAMINE uv.fm 
STRUCT\main\uv. fm: 3.0000001E+10 
DBG> STEP 
stepped to STRUCT\main\%LINE 32 
ae 
DBG> EXAMINE/ASCII uv.cm 
STRUCT\main\uv.cm: Hah 


The following example, which defines a structure, is used to show debugger 
support for operators. 


main () 

{ 
int. count; i= 1; 
char c= A’; 
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struct 
{ 
int digit; 
char alpha; 
}  tbl[27], *p; 


for (count = 0; count <= 26; count+t) 
{ 
tbl[count].digit 
tbl [count] .alpha 
} 


itt. 
ctt+; 


ou 


} 


The first EVALUATE command that follows uses C syntax to refer to the address 
of a variable. It is equivalent to the second command, which uses the /ADDRESS 
qualifier to obtain the address of the variable. 

DBG> EVALUATE &tbl 

2146736881 


DBG> EVALUATE/ADDRESS tbl 
2146736881 


You can evaluate individual members of an aggregate; the debugger returns the 
value of the member: 


DBG> EVALUATE tbl [2] .digit 
3 


When you perform pointer arithmetic, the debugger displays a message indicating 
the scale factor that has been applied. It then returns the address resulting from 
the arithmetic operation. A subsequent EXAMINE command at that address 
returns the value of the variable: 
DBG> EVALUATE tbl + 4 
SDEBUG-I-SCALEADD, pointer addition: scale factor of 5 applied to 
right argument 
2146736901 
DBG> EXAMINE 2146736901 
ARSTRUCT\main\tbl [4] .digit: 5 
You can use the EVALUATE command to perform arithmetic operations on 
program variables: 
DBG> EVALUATE tbl[4].digit * 2 
10 
The debugger enters a message when you use an unsupported operator: 


DBG> EVALUATE countt+t+ 
SDEBUG-W-SIDEFFECT, operators with side effects not supported (++, --) 


E.5 COBOL 


This section describes debugger support for COBOL. 
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E.5.1 Operators in Language Expressions 
Supported COBOL operators in language expressions follow: 


Kind 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 


Symbol 


+ 


Function 


Unary plus 

Unary minus (negation) 
Addition 

Subtraction 
Multiplication 

Division 
Exponentiation 

Equal to 

Not equal to 

Greater than 

Greater than or equal to 
Less than 

Less than or equal to 
Logical NOT 

Logical AND 

Logical OR 


E.5.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for COBOL follow: 


Symbol Construct 

() Subscripting 

OF Record component selection 
IN Record component selection 


E.5.3 Data Types 


Supported COBOL data types follow: 


COBOL Data Type 


COMP 

COMP 

COMP 
COMP-1 
COMP-2 
COMP-3 
INDEX 
Alphanumeric 
Records 
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VAX Data Type Name 


Longword Integer (L,LU) 
Word Integer (W,WU) 
Quadword Integer (Q,QU) 
F_Floating (F) 
D_Floating (D) 

Packed Decimal (P) 
Longword Integer (L) 
ASCII Text (T) 

(None) 
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E.5 COBOL 
~ COBOL Data Type VAX Data Type Name 
Numeric Unsigned - Numeric string, unsigned (NU) 
_ Leading Separate Sign - Numeric string, left separate sign (NL) 
' Leading Overpunched Sign Numeric string, left overpunched sign (NLO) 
Trailing Separate Sign Numeric string, right separate sign (NR) 
Trailing Overpunched Sign Numeric string, right overpunched sign (NRO) 


E.5.4 Source Display 


The debugger can show source text included in a program with the COPY, COPY 
REPLACING, or REPLACE statement. However, when COPY REPLACING 

or REPLACE is used, the debugger shows the original source text instead of 
the modified source text generated by the COPY REPLACING or REPLACE 
statement. 


The debugger cannot show the original source lines associated with the code for 
a REPORT section. You can see the DATA SECTION source lines associated 
with a REPORT, but no source lines are associated with the compiled code that 
generates the report. 


E.6 DIBOL 
This section describes debugger support for DIBOL. 


E.6.1 Operators in Language Expressions 
Supported DIBOL operators in language expressions follow: 


Kind Symbol Function 

Prefix # Round 

Prefix + Unary plus 

Prefix - Unary minus (negation) 
Infix + Addition 

Infix - Subtraction 

Infix * Multiplication 

Infix / Division 

Infix // Division with fractional result 
Infix HQ. Equal to 

Infix .NE. Not equal to 

Infix GT. Greater than 

Infix .GE. Greater than or equal to 
Infix .LT. Less than 

Infix .LE. Less than or equal to 
Infix .NOT. Logical NOT 

Infix AND. Logical AND 

Infix .OR. Logical OR 

Infix XOR. Exclusive OR 
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E.6.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for DIBOL follow: 


Symbol 


() 
C] 


E.6.3 Data Types 


Construct 


Substring 
Subscripting 


Record component selection | 


Supported DIBOL data types follow: 


DIBOL Data Type 


Il 

I2 

14 

Pn 
Pn.m 
Dn 
Dn.m 
An 
Arrays 


Records 


E.7 FORTRAN 


VAX Data Type Name 


Byte Integer (B ) 

Word Integer ( W ) 

Longword Integer (L) 

Packed Decimal String (P) 
Packed Decimal String (P) 
Numeric String, Zoned Sign (NZ) 
Numeric String, Zoned Sign (NZ) 
ASCII Text (T) 

(None) 

(None) 


This section describes debugger support for FORTRAN. 


E.7.1 Operators in Language Expressions | 
Supported FORTRAN operators in language expressions follow: 


Kind 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
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Symbol 


Function 


Unary plus 

Unary minus (negation) 
Addition 

Subtraction 
Multiplication 

Division 
Exponentiation 
Concatenation 

Equal to 

Not equal to 

Greater than 

Greater than or equal to 
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Kind Symbol Function 
Infix LT. Less than 
Infix LE. Less than or equal to 
Prefix NOT. Logical NOT 
Infix AND. Logical AND 
Infix -OR. Logical OR 
Infix XOR. Exclusive OR 
Infix .EQV. Equivalence 
Infix .NEQV. Exclusive OR 


E.7.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for FORTRAN follow: 


Symbol Construct 


() Subscripting 


Record component selection 


E.7.3 Predefined Symbols 
Supported FORTRAN predefined symbols follow: 


Symbol Description 
.TRUE. Logical True 
FALSE. Logical False 


E.7.4 Data Types 
Supported FORTRAN data types follow: 


FORTRAN Data Type VAX Data Type Name 
LOGICAL*1 Byte Unsigned (BU) 
LOGICAL*2 Word Unsigned (WU) 
LOGICAL*4 Longword Unsigned (LU) 
INTEGER*2 Word Integer (W ) 
INTEGER*4 Longword Integer (L) 
REAL*4 F_Floating (F) 
REAL*8 D_Floating (D) 
REAL*8 G_Floating (G) 
REAL*16 H_Floating (H) 
COMPLEX*8 F_Complex (FC) 
COMPLEX*16 D_Complex (DC) 
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FORTRAN Data Type VAX Data Type Name 
COMPLEX*16 G_Complex (GC) 
CHARACTER ASCII Text (T) 
Arrays (None) 
Records (None) 


Even though the VAX data type codes for unsigned integers (BU, WU, LU) are 
used internally to describe the LOGICAL data types, the debugger (like the 
compiler) treats LOGICAL variables and values as being signed when used in 
language expressions. 


The debugger prints the numeric values of LOGICAL variables or expressions 
instead of .TRUE. or .FALSE. Normally, only the low-order bit of a LOGICAL 
variable or value is significant (0 is .FALSE. and 1 is .TRUE.). However, 
VAX FORTRAN does allow all bits in a LOGICAL value to be manipulated 
and LOGICAL values can be used in integer expressions. For this reason, it 
is at times necessary to see the entire integer value of a LOGICAL variable or 
expression, and that is what the debugger shows. 


COMPLEX constants such as (1.0,2.0) are not supported in debugger expressions. 


Floating point numbers of type REAL*8 and COMPLEX*16 may be represented 
by D_Floating or G_Floating depending on compiler switches. . 


E.7.5 Initialization Code 


When you invoke the debugger for a program compiled with the 
/CHECK=UNDERFLOW or /PARALLEL qualifier, the following message appears: 


5 RUN FORMS 
VAX DEBUG Version 5.5 


SDEBUG-I-INITIAL, language is FORTRAN, module set to FORMS 
SDEBUG-I-NOTATMAIN, type GO to get to start of main program 
DBG> 


The “NOTATMAIN” message indicates that execution is supended before the start 
of the main program, so that you can execute initialization code under debugger 
control. Typing the GO command places you at the start of the main program. At 
that point, type the GO command again to start program execution, as with other 
types of FORTRAN programs. 


E.86 MACRO-32 


This section describes debugger support for MACRO-32. 


E.8.1 Operators in Language Expressions 
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Language MACRO does not have expressions in the same sense as high-level 
languages. Only assembly-time expressions and only a limited set of operators 
are accepted. To permit the MACRO programmer to use expressions at debug- 
time as freely as in other languages, the debugger accepts a number of operators 
in MACRO language expressions that are not found in MACRO itself. In 
particular, the debugger accepts a complete set of comparison and Boolean 
operators modeled after BLISS. It also accepts the indirection operator and the 
normal arithmetic operators. 
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Kind Symbol Function 
Prefix @ Indirection 
Prefix : Indirection 
Prefix + Unary plus 
Prefix - Unary minus (negation) 
Infix + Addition 
Infix - Subtraction 
Infix - Multiplication 
Infix / Division 
Infix MOD Remainder 
Infix @ Left shift 
Infix EQL Equal to 
Infix EQLU Equal to 
Infix NEQ Not equal to 
Infix NEQU Not equal to 
Infix GTR Greater than 
Infix GTRU Greater than unsigned 
Infix GEQ Greater than or equal to 
Infix GEQU Greater than or equal to unsigned 
Infix LSS Less than 
Infix LSSU Less than unsigned 
Infix LEQ Less than or equal to 
Infix LEQU Less than or equal to unsigned 
Prefix NOT Bit-wise NOT 
Infix AND Bit-wise AND 
Infix OR Bit-wise OR 
Infix XOR Bit-wise exclusive OR 
Infix EQV Bit-wise equivalence 


E.8.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for MACRO-32 follow: 


Symbol Construct 
[] Subscripting 
<p,s,e> Bitfield selection as in BLISS 


The DST information generated by the MACRO assembler treats a label that 

is followed by an assembler directive for storage allocation as an array variable 
whose name is the label. This enables you to use the array syntax of a high-level 
language when examining or manipulating such data. 


In the following example of MACRO source code, the label LAB4 designates 
hexadecimal data stored in four words: 


LAB4: . WORD AKSE, 912], °X3€ 


E~35 


Summary of Debugger Support for Languages 
E.8 MACRO-32 


The debugger treats LAB4 as an array variable. For example, the next command 
displays the value stored in each element (word): 


DBG> EXAMINE LAB4 


.MAIN. \MAIN\LAB4 


[0]: 
[iis 
[2]: 
{3}: 


003F 
0005 
0005 
003C 


The next command displays the value stored in the fourth word (the first word is 


indexed as element “0O”): 


DBG> EXAMINE LAB4[3] 
.MAIN. \MAIN\LAB4 [3]: 


E.8.3 Data Types 
Supported MACRO-32 data types follow: 


MACRO-32 Data Type 


03C 


VAX Data Type Name 


(Not applicable) Byte Unsigned (BU) 
(Not applicable) Word Unsigned (WU) 
(Not applicable) Longword Unsigned (LU) 
(Not applicable) Byte Integer (B) 

(Not applicable) Word Integer (W) 

(Not applicable) Longword Integer (L) 
(Not applicable) F_Floating (F) 

(Not applicable) D_Floating (D) 

(Not applicable) G_Floating (G) 

(Not applicable) H_Floating (H) 


(Not applicable) 


Packed decimal (P) 


E.9 Pascal 


This section describes debugger support for Pascal. 


E.9.1 Operators in Language Expressions 
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Supported Pascal operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix - Unary minus (negation) 
Infix + Addition, concatenation 
Infix - Subtraction 

Infix - Multiplication 

Infix / Real division 

Infix DIV Integer division 

Infix MOD Modulus 


Kind 


Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Prefix 
Infix 
Infix 


Symbol 
REM 


2 


NOT 
AND 
OR 


Summary of Debugger Support for Languages 
E.9 Pascal 


Function 


Remainder 
Exponentiation 

Set membership 
Equal to 

Not equal to 

Greater than 
Greater than or equal to 
Less than 

Less than or equal to 
Logical NOT 

Logical AND 

Logical OR 


The typecast operator (::) is not supported in language expressions. 


E.9.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for Pascal follow: 


Symbol 
[] 


Construct 


Subscripting 


Record component selection 


Pointer dereferencing 


E.9.3 Predefined Symbols 
Supported Pascal predefined symbols follow: 


Symbol 
TRUE 
FALSE 
NIL 


Meaning 


Boolean True 


Boolean False 


Nil pointer 


E.9.4 Built-In Functions 
Supported Pascal built-in functions follow: 


Symbol 


SUCC 
PRED 


Meaning 


Logical successor 


Logical predecessor 
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E.9.5 Data Types 
Supported Pascal data types follow. 


E.9.6 Additional Information 
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Pascal Data Type 


INTEGER 
INTEGER 
INTEGER 
UNSIGNED 
UNSIGNED 
UNSIGNED 
SINGLE 
DOUBLE 
DOUBLE 
QUADRUPLE 
BOOLEAN 
CHAR 
VARYING OF CHAR 
SET 

FILE 
Enumerations 
Subranges 
Typed Pointers 
Arrays 
Records 


Variant records 


VAX Data Type Name 


Longword Integer (L) 
Word Integer (W,WU) 
Byte Integer (B,BU) 
Longword Unsigned (LU) 
Word Unsigned (WU) 
Byte Unsigned (BU) 
F_Floating (F) 
D_Floating (D) 
G_Floating (G) 
H_Floating (H) 
(None) 

ASCII Text (T) 
Varying Text (VT) 
(None) 

(None) 

(None). 

(None) 

(None) 

(None) 

(None) 

(None) 


The debugger accepts Pascal set constants such as [1,2,5,8..10] or (RED, BLUE] 
in Pascal language expressions. 


In general, you can examine, evaluate, and deposit into variables, record 
fields, and array components. An exception to this occurs under the following 
circumstances: if a variable is not referenced in a program, the VAX Pascal 
compiler might not allocate the variable. If the variable is not allocated and you 
try to examine it or deposit into it, you will receive an error message. 


When you deposit data into a variable, the debugger truncates the high-order 
bits if the value being deposited is larger than the variable; it fills the high-order 
bits with zeros if the value being deposited is smaller than the variable. If the 
deposit violates the rules of assignment compatibility, the debugger displays an 


informational message. 


You can examine and deposit into automatic variables (within any active block); 
however, because automatic variables are allocated in stack storage and are 
contained in registers, their values are considered undefined until the variables 
are initialized or assigned a value. 
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E.9.7 Restrictions 


E.10 PL/I 


Restrictions in debugger support for Pascal are as follows. 


You can examine a VARYING OF CHAR string. But you cannot examine the 
.LENGTH or .BODY fields using the normal language syntax. For example, if 
VARS is the name of a string variable, the following commands are not supported: 


DBG> EXAMINE VARS.LENGTH 
DBG> EXAMINE VARS.BODY 


To examine these fields, use the techniques illustrated in the following examples. 


Use Instead of 
EXAMINE/WORD VARS EXAMINE VARS.LENGTH 
EXAMINE/ASCII VARS+2 EXAMINE VARS.BODY 


This section describes debugger support for PL/I. 


E.10.1 Operators in Language Expressions 


Supported PL/I operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix _ Unary minus (negation) 
Infix + Addition 

Infix - Subtraction 

Infix 53 Multiplication 

Infix / Division 

Infix == Exponentiation 

Infix 1 | Concatenation 

Infix mm Equal to 

Infix i Not equal to 

Infix > Greater than 

Infix >= Greater than or equal to 
Infix N< Greater than or equal to 
Infix < Less than 

Infix <= Less than or equal to 
Infix Ns Less than or equal to 
Prefix fs Bit-wise NOT 

Infix & Bit-wise AND 

Infix | Bit-wise OR 
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E.10.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for PL/I follow: 


Symbol Construct 


() Subscripting 


Structure component selection 


-> Pointer dereferencing 


E.10.3 Data Types 


Supported PL/I data types follow: 


PL/I Data Type 


FIXED BINARY 
FIXED DECIMAL 
FLOAT BIN/DEC 
FLOAT BIN/DEC 
FLOAT BIN/DEC 
FLOAT BIN/DEC 
BIT 

BIT 
CHARACTER 
CHARACTER VARYING 
FILE 

Labels 

Pointers 

Arrays 


Structures 


VAX Data Type Name 


Byte- (B), Word- (W), or Longword- (L) Integer 
Packed Decimal (P ) 
F_Floating (F) 
D_Floating (D) 
G_Floating (G) 
H_Floating (H) 

Bit (V) 

Bit Unaligned (VU) 
ASCII Text (T) 
Varying Text (VT) 
(None) 

(None) 

(None) 

(None) 

(None) 


E.10.4 Static and Nonstatic Variables 


Variables of the following storage classes are allocated statically: STATIC, 
EXTERNAL, GLOBALDEF, and GLOBALREF. 


Variables of the following storage classes are allocated nonstatically (on the 
stack or in registers): AUTOMATIC, BASED, CONTROLLED, DEFINED, and 


PARAMETER. 


E.10.5 Examining and Manipulating Data 


This section gives examples showing use of the EXAMINE command with PL/I 
data types. It also highlights aspects of debugger support that are specific to 
PL/I. 
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E.10.5.1 EXAMINE Command Examples 


The following examples show use of the EXAMINE command with a few selected 
PL/I data types. 


Examine the value of a variable declared as FIXED DECIMAL (10,5): 


DBG> EXAMINE X 
PROG4\X: 540.02700 


Examine the value of a structure variable: 


DBG> EXAMINE PART 
MAIN PROG\INVENTORY_PROG\PART 


ITEM: "WF=1247" 
PRICE: 49.95 
IN STOCK: 24 


Examine the value of a pictured variable (note that the debugger displays the 
value in quotation marks): 

DBG> EXAMINE Q 

MAIN\Q: "666.3330" 


Examine the value of a pointer (which is the virtual address of the variable it 
accesses) and display the value in hexadecimal radix instead of decimal (the 
default): 


DBG> EXAMINE/HEXADECIMAL P 

PROG4\SAMPLE.P: 0000B2A4 

Examine the value of a variable with the BASED attribute; in this case, the 
variable X has been declared as BASED(PTR), with PTR its pointer: 

DBG> EXAMINE X 

PROG\X: SAM 


Examine the value of a variable X declared as BASED with a variable PTR 
declared as POINTER; here, PTR is associated with X by the following line of 
PL/I code (instead of X having been declared as BASED(PTR) as in the preceding 
example): 


_ ALLOCATE X SET (PTR); 


In this case, you examine the value of X as follows: 
DBG> EXAMINE PTR->X 
PROG6\PTR->X: as 
E.10.5.2 Notes on Debugger Support 
Note the following points about debugger support for PL/I. 


You cannot use the DEPOSIT command with entry or label variables or formats, 
or with entire arrays or structures. You cannot use the EXAMINE command with 
entry or label variables or formats; use the EVALUATE/ADDRESS command 
instead. 


You cannot use the EXAMINE command to determine the values or attributes 
of global literals (such as GLOBALDEF VALUE literals) because they are static 
expressions. Use the EVALUATE command instead. 


You cannot use the EXAMINE, EVALUATE, and DEPOSIT commands with 
compile-time variables and procedures. You can, however, use EVALUATE and 
DEPOSIT (but not EXAMINE) with a compile-time constant, as long as the 
constant is the source and not the destination. 
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Note that an uninitialized automatic variable does not have valid contents until 
after a value has been assigned to it. If you examine it before that point, the 
value displayed is unpredictable. 


You can deposit a value into a pointer variable either by depositing another 
pointer’s value into it, thus making symbolic reference to both pointers, or by 
depositing a virtual address into it. (You can find out the virtual address of a 
variable by using the EVALUATE/ADDRESS command, and then deposit that 
address into the pointer.) When you examine a pointer, the debugger displays its 
value in the form of the virtual address of the variable that the pointer points to. 


The debugger treats all numeric constants of the form n or n.n in PL/I language 
expressions as packed decimal constants, not integer or floating-point constants, 
in order to conform to PL/I language rules. The internal representation of 10 is 
therefore 0C01 hexadecimal, not 0A hexadecimal. 


You can enter floating-point constants using the syntax nEn or n.nEn. 


There is no PL/I syntax for entering constants whose internal representation is 
Longword Integer. This limitation is not normally significant when debugging, 
since the debugger supports the PL/I type conversion rules. However, it is 
possible to enter integer constants by using the debugger’s HEX, %OCT, and 
%BIN operators, because nondecimal radix constants are assumed to be FIXED 
BINARY. For example, EVALUATE/HEXADECIMAL 53 + $HEX 0 displays 00000035. 


E.11 RPG Il 
This section describes debugger support for RPG II. 


E.11.1 Operators in Language Expressions 


The following operators are supported in language expressions when the language 
is set to RPG II: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix - | Unary minus (negation) 
Infix + Addition 

Infix _ Subtraction 

Infix * Multiplication 

Infix / Division 

Infix = Equal to 

Infix NOT = Not equal to 

Infix > Greater than 

Infix NOT < Greater than or equal to 
Infix < Less than 

Infix NOT > Less than or equal to 
Prefix NOT Logical NOT . 

Infix AND Logical AND 

Infix OR Logical OR 
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E.11.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for RPG II follow: 


Symbol Construct 


() Subscripting 


E.11.3 Data Types 
Supported RPG II data types follow: 


RPG Il Data Type VAX Data Type Name 
Longword binary numeric Longword Integer (L) 

Word binary numeric Word Integer ( W ) 

Packed decimal Packed Decimal (P ) 

Character ASCII Text (T) 

Overpunched decimal Right Overpunched Sign (NRO) 
Arrays (None) 

Tables (None) 


E.11.4 Setting Breakpoints or Tracepoints 


With RPG II programs, you can set breakpoints using source line numbers, logic 
cycle labels, user-defined tag names, and subroutine labels. Debugging RPG II 
programs is somewhat different from debugging programs in other languages, 
and the following paragraphs explain where and how you can set breakpoints or 
tracepoints. 


E.11.4.1 Setting Breakpoints or Tracepoints Within Specifications 


The following paragraphs describe where you can set breakpoints (or tracepoints) 
in specifications, using line numbers. 


The RPG II program cycle determines the order in which program lines are 
processed. When setting breakpoints or tracepoints, you can reference the line 
numbers that RPG II assigns to your program and appear in a listing file or ina 
debugger source display. The line numbers you specify in columns 1 through 5 of 
a specification are not used. 


The compiler assigns line numbers only to certain specifications at specific points 
in the logic cycle; therefore, you can specify a breakpoint or tracepoint at these 
points in the program: 


¢ A breakpoint at a File Description specification occurs before an input or 
update file is opened or just before an output file is created. The line number 
of this breakpoint corresponds to the File Description specification for this 
file. 


¢ A breakpoint at an Input specification occurs before the fields are loaded with 
data from a record. The line number of this breakpoint corresponds to the 
record definition in an Input specification. 
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You can set two breakpoints for each Calculation specification. The first 
breakpoint occurs just after testing control-level indicators, if used, and just 
before testing conditioning indicators. The second breakpoint occurs just 
before executing the operation code. Use the following syntax: 


SET BREAK /ine-number.statement-number 


For example, assume that a Calculation specification begins with line number 
25. The command SET BREAK 25.1 enables you to test indicators. The 
command SET BREAK 25.2 puts a breakpoint just before the operation code 
is executed. If a Calculation specification has no conditioning indicators, the 
command SET BREAK 25 puts a breakpoint just before the operation code is 
executed. 


You can specify statement numbers only with Calculation specifications that 
have conditioning indicators. 


A breakpoint at an Output specification occurs after the output buffer has 
been built but before the record is output. The line number of the breakpoint 
corresponds to the record definition in an Output specification. 


E.11.4.2 Setting Breakpoints or Tracepoints on Labels 


You can specify an RPG II label as a breakpoint or a tracepoint. The following 
RPG II labels, which correspond to specific points in the logic cycle, are provided 
in addition to user-defined tags. Note that these labels do not appear in the 
source code but are accessible from the debugger. The labels do appear in the 
machine code listing. 
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*DETL Breaks just before outputting heading and detail lines 

*GETIN Breaks just before reading the next record from the primary or 
secondary file 

*TOTC Breaks just before performing total-time calculations 

*TOTL Breaks just before performing total-time output 

*OFL Breaks just before performing overflow output 

*DETC Breaks just before performing detail-time calculations 


For example: 
DBG> SET BREAK *TOTL 


E.11.5 EXAMINE Command 


The EXAMINE command enables you to look at the contents of a variable, the 
current table entry, an array element, or the I/O buffer. 


To examine an array variable, use array syntax as in the following example: 


DBG> EXAMINE ARR3 (9) ! Display element 9 of array ARR3 
DBG> EXAMINE ARRY(1:7) ! Display elements 1-7 of array ARRY 


Specifying a table name enables you to examine the entry retrieved from the 
last LOKUP operation. 
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To display the contents of the I/O buffer, specify the name of the input file, 
update file, or output file, followed by the string $BUF. For example, the 
following command displays the contents of the I/O buffer for the input file 
INPUT: 


DBG> EXAMINE INPUTSBUF 

The following command displays the ASCII equivalent of the string STRING, 
which is 6 characters long: 

DBG> EXAMINE/ASCII:6 STRING 


To examine a variable which contains the at sign (@), use 2 NAME as follows: 
DBG> EXAMINE $NAME ’ITEM@’ 


To examine a nonexternal indicator, precede it with the string *IN. For 
example: 


DBG> EXAMINE *IN56 
*INS6: "0" 


If an indicator is set off, 0 is displayed. If an indicator is set on, 1 is 
displayed. 

You cannot examine external indicators in this manner. To examine external 
indicators, you must first link the program with the /NOSYSSHR LINK 
command qualifier; then, use the CALL command, as in the following 
example which displays the value of U5: 


DBG> CALL RPGSEXT_INDS (5) 
value returned is 0 


E.11.6 DEPOSIT Command 
Note the following points when using the DEPOSIT command: 


You can deposit a single value into an element of an array using array syntax 
as in the following example, which deposits the value 150 into element 2 of 
array ARR: 


DBG> DEPOSIT ARR(2) = 150 


You can deposit multiple values into an array of character strings, by using 
the /ASCII qualifier with the DEPOSIT command. For example, assume 
PARTS is an array of 10 elements in program INV.RPG, each a character 
string of length 3. The following DEPOSIT command deposits the strings 
P04, P05, and P06 into elements 4, 5, and 6, respectively, of array PARTS: 


DBG> DEPOSIT/ASCII PARTS(4) = "PO4P05P06" 
DBG> EXAMINE PARTS (4:6) 
INV\PARTS 

(4): 'PQ4’ 

(5): P05’ 

(6): "P06! 


Values deposited into numeric fields are aligned on the decimal point. Shorter 
fields are padded with zeros to the left and right of the decimal point. 


Values deposited into character fields are left justified. If the value contains 
fewer characters than the character field, the field is padded on the right with 
spaces. 
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¢ To set a nonexternal indicator on or off with the DEPOSIT command, precede 
the indicator with the string *IN. Depositing the value 1 or 0 sets the 
indicator on or off, respectively. For example, the following command sets 
indicator 56 on: 


DBG> DEPOSIT *IN56 = "1" 


E.11.7 EDIT Command 


The EDIT command invokes the RPG II editor rather than the VAX Language- 
Sensitive Editor. 


E.12 SCAN 
This section describes debugger support for SCAN. 


E.12.1 Operators in Language Expressions 
Supported SCAN operators in language expressions follow: 


Kind Symbol Function 

Prefix + Unary plus 

Prefix - Unary minus (negation) 
Infix + Addition 

Infix - Subtraction 

Infix * Multiplication 

Infix / Division 

Infix & Concatenation 

Infix = Equal to 

Infix <> Not equal to 

Infix > Greater than 

Infix >= Greater than or equal to 
Infix < Less than 

Infix <= Less than or equal to 
Prefix NOT Complement 

Infix AND Intersection 

Infix OR Union 

Infix XOR Exclusive OR 


E.12.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for SCAN follow: 


Symbol Construct 


() Subscripting 
Record component selection 


-> Pointer dereferencing 
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E.12.3 Predefined Symbols 
Supported SCAN predefined symbols follow: 


Symbol Meaning 
TRUE Boolean True 
FALSE Boolean False 
NIL Nil pointer 


E.12.4 Data Types 
Supported SCAN data types follow: 


SCAN Data Type VAX Data Type Name 
BOOLEAN (None) 

INTEGER Longword Integer (L) 
POINTER (None) 

FIXED STRING (n) TEXT with CLASS=S 
VARYING STRING (n) TEXT with CLASS=VS 
DYNAMIC STRING TEXT with CLASS=D 
TREE . (None) 

TREEPTR (None) 

RECORD (None) 

OVERLAY (None) 


There is no specific support for the following datatypes: FILE, TOKEN, GROUP, 
SET. 
E.12.5 Names 
You can use the names of the following SCAN constructs in debugger commands: 
procedures, macros, constants, variables, and labels. 
E.12.6 Controlling Execution 
Note the following points about SCAN breakpoints, tracepoints, and watchpoints. 


E.12.6.1 Breakpoints and Tracepoints 


You can set breakpoints and tracepoints on procedures, trigger macros, syntax 
macros, and labels, in addition to line numbers. For example: 


DBG> SET BREAK find keyword ! break on a trigger macro 
DBG> CANCEL BREAK exit ! cancel break on label 
DBG> SET BREAK = compare_trees ! break on a procedure 


Conventional breakpoints and tracepoints are not especially convenient for 
monitoring SCAN’s picture matching. Where do you set a breakpoint or 
tracepoint to observe the tokens built by your program? There is no statement in 
your program on which to set such a breakpoint. 


To solve this problem, VAX SCAN defines several events. By setting breakpoints 
or tracepoints on these events, you can observe the picture matching process. 
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The following event keywords are defined for SCAN programs. 


Event Keyword Description 

TOKEN A token is built. 

PICTURE An operand in a picture is being matched. 

INPUT A new line of the input stream is read. 

OUTPUT A new line of the output stream is written. 

TRIGGER A trigger macro is starting or terminating. 

SYNTAX A syntax macro is starting or terminating. 

ERROR Picture matching error recovery is starting or terminating. 


Use these keywords with the /EVENT qualifier of the SET BREAK, SET TRACE, 
CANCEL BREAK, and CANCEL TRACE commands. For example, the following 
command sets a breakpoint that triggers whenever a TOKEN is built: 


DBG> SET BREAK/EVENT=TOKEN 


Recognition of SCAN events is enabled automatically by the debugger if the main 
program is written in SCAN. If you are debugging a program written in another 
language that calls a SCAN routine, proceed as follows to set up the SCAN 
environment: 


1. 


Enter the SET LANGUAGE SCAN command to enable recognition of 
language-dependent operators, expressions, and other constructs. (See the 
description of the SET LANGUAGE command.) 


Enter the SET EVENT_FACILITY SCAN command to enable recognition of 
SCAN events. (See the description of the SET EVENT_FACILITY command.) 
The SHOW EVENT_FACILITY command identifies the current facility and 
its events. 


E.12.6.2 Watchpoints 
Note the following points about SCAN watchpoints: 


Variables declared at MODULE level are static by default. 


Variables declared at PROCEDURE or MACRO level are automatic 
(nonstatic) by default. 


DYNAMIC STRING variables are dynamically built. The storage used to 
hold the value of the string can change when the value of the string changes. 
Thus, the storage the debugger is watching may not be the correct storage if 
the string’s value is changed. 


E.12.7 Examining and Depositing 


The following sections describe how to examine and deposit into the following 
SCAN variables: 
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STRING 
FILL 
POINTER 
TREE 
TREEPTR 
RECORD 
OVERLAY 
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E.12.7.1 STRING Variables 


If you deposit into a FIXED STRING variable, truncation will occur if the 
deposited string is longer than the size established by the declaration of that 
variable. 


If you deposit into a VARYING STRING variable, truncation will occur if the 
deposited string is longer than the maximum size established by the declaration 
of that variable. 


If you deposit into a DYNAMIC STRING variable, truncation will occur if the 
deposited string is longer than the current size of the variable. 


With FIXED and DYNAMIC STRING variables, if the deposited string is shorter 
than the current size of the variable, the unfilled portion of the variable will be 
blank padded to the right, with the new string left justified in the variable. 


In the case of VARYING STRING variables, the current size of the variable 
storage space will be adjusted to the size of the deposited string. 


E.12.7.2 FILL Variables 


Examining a FILL variable causes the contents of the specified variable to 

be displayed as a string, by default, and so may have little meaning. If the 
characteristics (or type) of the fill are known, the appropriate qualifier applied to 
the command will produce a more meaningful display. The following command 
example shows a fill x that is known to be a single floating number: 


DBG> EXAMINE/FLOAT x 


E.12.7.3 POINTER Variables 
You can examine a POINTER by name to find the address of the variable it points 
to. Use the operator that combines the minus sign and the greater than symbol 
(—>) to examine the variable that is based on the POINTER. 


Consider these declarations and assignments: 


TYPE symnode: RECORD 
ptr: POINTER TO symnode, 
vstr: VARYING STRING( 20 ), 


END RECORD; 
DECLARE x : symnode; 
DECLARE xptr: POINTER TO symnode; 
xptr = POINTER (x); 
X.vstr = ‘prehensile’; 


The following command displays the value of the vstr component of x: 


DBG> EXAMINE x.vstr 
POINTER\MAINPOINTER\X.VSTR: ‘prehensile’ 


The following command displays the value of vstr based on the POINTER: 


DBG> EXAMINE xptr->.vstr 
POINTER\MAINPOINTER\XPTR->.VSTR: ‘prehensile ' 
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E.12.7.4 TREE and TREEPTR Variables 
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You can examine the contents of the nodes in a tree using the following syntax: 
EXAMINE tree_variable({[subscript], ... ) 
You cannot deposit into a TREE variable. 


The following declarations and assignments describe a 2-level tree having 
both string and integer subscripts. This data structure is then used in several 
examples which show how to examine TREE and TREEPTR variables. 


MODULE debug tree; 


DECLARE voters : TREE ( STRING, INTEGER) OF INTEGER; 
DECLARE cityptr : TREEPTR ( STRING ) TO TREE (INTEGER) OF INTEGER; 
DECLARE wardptr : TREEPTR ( INTEGER ) TO INTEGER; 
PROCEDURE debug_exercise MAIN; 

voters ( ‘salem’, 1 ) = 2500; 

voters ( ‘salem’, 2 ) = 1500; 

voters ( ‘hudson’, 1 ) = 3500; 

voters ( ‘hudson’, 2 ) = 3200; 

voters ( ‘hudson’, 3 ) = 2900; 

voters ( 'zork’, 1 ) = 1000; 

cityptr = TREEPTR ( voters ( ‘hudson’ ) ); 


wardptr = TREEPTR ( voters ( ‘hudson’, 2 ) ); 
END PROCEDURE /* debug exercise */; 
END MODULE /* debug tree */; 


If you specify the name of a tree with the EXAMINE command, the debugger 
displays the contents of all nodes and leaves of the tree. For example: 

DBG> EXAMINE voters 

DEBUG _TREE\VOTERS 


‘hudson’ 
1: 3500 
2: 3200 
3 2900 
‘salem’ 
1: 2500 
2 1500 
'zork’ 
Ee 1000 


You can specify an interior node by entering the subscript for that node. For 
example: 


DBG> EXAMINE voters (’ salem’ ) 


DEBUG TREE\VOTERS (‘salem’) 
a 2500 
2 1500 


You can examine the leaf node in a tree by specifying all subscripts leading to the 
desired leaf. For example: 


DBG> EXAMINE voters (’ salem’, 2) 
DEBUG _TREE\VOTERS (’ salem’ ,2): 1500 


If you examine a TREEPTR variable, such as cityptr or wardptr, the debugger 
displays the address of that tree node. 


The following example shows how to examine what a TREEPTR variable is 
pointing to. 


DBG> EXAMINE cityptr-> 
DEBUG _TREE\CITYPTR-> 


DBG> EXAMINE wardptr-> 


1: 3500 
2: 3200 
oe 2900 
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DEBUG_TREEDEBUG TREE\WARDPTR->: 3200 


E.12.7.5 RECORD and OVERLAY Variables 


If you specify a RECORD by name with the EXAMINE command, all components 
of the RECORD are presented. To examine individual components of the 
RECORD, specify the full name of each component. 


The general format is as follows: 


EXAMINE recordname 
EXAMINE recordname.componentname.componentname ... 


You examine an OVERLAY in the same way. All components are again 
presented; thus, if a four-byte region is a FILL(4), an INTEGER, and a VARYING 
STRING(2), the four bytes will be displayed three different ways. 


E.13 Language UNKNOWN 


This section describes debugger support for language UNKNOWN. 


E.13.1 Operators in Language Expressions 
Supported operators in language expressions for language UNKNOWN follow: 


Kind 
Prefix 
Prefix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 
Infix 


Symbol 


<= 
EQL 
NEQ 
GTR 
GEQ 


Function 


Unary plus 

Unary minus (negation) 
Addition 

Subtraction 
Multiplication 

Division 
Exponentiation 
Concatenation 
Concatenation 

Equal to 

Not equal to 

Not equal to 

Greater than 

Greater than or equal to 
Less than 

Less than or equal to 
Equal to 

Not equal to 

Greater than 


Greater than or equal to 
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Kind Symbol 
Infix LSS 
Infix LEQ 
Prefix NOT 
Infix AND 
Infix OR 
Infix XOR 
Infix EQV 


Function 


Less than 

Less than or equal to 
Logical NOT 

Logical AND 

Logical OR © 
Exclusive OR 
Equivalence 


E.13.2 Constructs in Language and Address Expressions 
Supported constructs in language and address expressions for language 


UNKNOWN follow: 
Symbol Construct 
[J Subscripting 
() Subscripting 


Record component selection 


Pointer dereferencing 


E.13.3 Predefined Symbols 
Supported predefined symbols for language UNKNOWN follow: 


E.13.4 Data Types 
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Symbol 
TRUE 


FALSE 
NIL 


Meaning 


Boolean True 
Boolean False 
Nil pointer 


When the language is set to UNKNOWN, the debugger understands all data 
types accepted by other languages except a few very language-specific types, 
such as picture types and file types. In UNKNOWN language expressions, the 
debugger accepts most scalar VAX Standard data types. 


¢ For language UNKNOWN, the debugger accepts the dot-notation for record 
component selection. If C is a component of a record B which in turn is a 
component of a record A, C can be referenced as “A.B.C”. Subscripts can be 
attached to any array components; if B is an array, for instance, C can be 
referenced as “A.B[2,3].C”. 


e For language UNKNOWN, the debugger accepts both round and square 
subscript parentheses. Hence, A[2,3] and A(2,3) are equivalent. 


A 


Abort function, 2-7, 10-9, CD-38, CD-121, 
CD-204 
with DECwindows, 1~—20 
/ABORT qualifier, CD-178 
/AC 
See /ASCIC qualifier 
/ACTIVATING qualifier, 10-12, CD~-17, CD-30, 
CD-125, CD-184 
Activation 
predefined tracepoint, multiprocess program, 
10-12 
/ACTIVE qualifier, 12-10, 12-28, CD-179 
%ACTIVE_TASK, 12-10, 12-14 
/AD 
See /ASCID qualifier 
%ADAEXC_NAME, 9-15, D~9 
%ADDR, CD-10 
Address . 
depositing into, 4—23 
with DECwindows, 1-25 
examining, 4-13 
with DECwindows, 1-25 
obtaining, 3-12, 4-12 
with DECwindows, 1~24 
specifying breakpoint, 3-11 
symbolizing, 4-13 
with DECwindows, 1-25 
Address expression 


See also Address 
code, 3-10, 4-18, 6-4 
with DECwindows, 1-22 
compared to language expression, 4—7 
with DECwindows, 1-22 
composite, 3-11 
vector, 11-16 
current entity, 4—8, 4-13, D-5 
with DECwindows, 1-9 
DEPOSIT command, 4-3, CD-58 
EVALUATE/ADDRESS command, 3-12, 4—12, 
CD-79 
EXAMINE command, 4—2, CD-81 
EXAMINE/SOURCE command, 6-4 
logical predecessor, 4—8, 4-13, D-5 
with DECwindows, 1-9 


index 


Address expression (cont’d) 
logical successor, 4—8, 4-13, D-5 
with DECwindows, 1-9 
selecting from DECwindows window, 1-22 
SET BREAK command, 3-8, CD~124 
SET TRACE command, 3—9, CD-183 
SET WATCH command, 3-15, CD-196 
symbolic, 44 
with DECwindows, 1-22 
SYMBOLIZE command, 4-13, CD—263 
type of, 4-4 
/ADDRESS qualifier, 8-6, CD-47, CD-79, 
CD-243 
/AFTER qualifier, CD-125, CD-184, CD-196 
Aggregate 
DEPOSIT command, 4-16, 4-17, 11-6, 11-7, 
CD-58 
EXAMINE command, 4-16, 4-17, 11-6, 11-7, 
CD-81 
SET WATCH command, 3-17, 11-3 
ALLOCATE command 
debugging with two terminals, 9-5 
/ALL qualifier, CD-158 
CANCEL BREAK command, CD-17 
CANCEL DISPLAY command, CD-—20 
CANCEL IMAGE command, CD—22 
CANCEL MODULE command, CD-24 
CANCEL TRACE command, CD-30 
CANCEL WATCH command, CD-34 
CANCEL WINDOW command, CD-35 
DELETE command, CD-54 
DELETE/KEY command, CD-—56 
EXTRACT command, CD-97 
SEARCH command, CD~-115 
SET IMAGE command, CD-138 
SET MODULE command, CD-152 
SET TASK command, CD-179 
SHOW DISPLAY command, CD-212 
SHOW KEY command, CD-218 
SHOW PROCESS command, CD~229 
SHOW TASK command, 12-13, 12-19, CD-246 
SHOW WINDOW command, CD-255 
%AP, 4-22, D-3 
Apostrophe (’) - 
ASCII string delimiter, 4-15 
instruction delimiter, 4—21 
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/APPEND qualifier, CD-97 

Array type, 4-16 
vector register, 11-6 

/ASCIC qualifier, CD-58, CD-81 

/ASCID qualifier, CD-59, CD-81 

/ASCII qualifier, CD-59, CD-82 

ASCII string type, 4-15, 4-26, CD-58, CD-81, 

CD-191 

/ASCIW qualifier, CD-59, CD-82 

/ASCIZ qualifier, CD-59, CD-82 

AST (asynchronous system trap), 9-16 
CALL command, 9-16, CD-10 
disabling, CD-64 
displaying AST handling conditions, CD-—205 
enabling, CD-—76 
SHOW CALLS command, 9-16 

AST-driven program 
debugging, 9-16 

Asterisk (*) 
HELP command, CD-102 
multiplication operator, D-7 

/AST qualifier, 9-16, CD-11 

At sign (@) 
contents-of operator, D~7 
execute-procedure command, 8-1, CD-7 
SET ATSIGN command, CD-123 
SHOW ATSIGN command, CD-—206 

ATTACH command, 3—4, CD-9 

Attribute 


display, 7-3, 7-6, 7-9, 7-18, CD-117, CD-238 


window 
with DECwindows, 1-10 
AUTO window, DECwindows, 1-11 
/AW 
See /ASCIW qualifier 
/AZ 
See /ASCIZ qualifier 


Backslash (\ ) 
current value, 4-6 
global-symbol specifier, 5-10, CD-166, D-7 
path name delimiter, 5-9, 6-4, D—7 
with DECwindows, 1-10, 1-26 
%BIN, 4-11, D-5 
/BINARY qualifier, 4-11, CD~77, CD-79, CD-82 
Bit field operator (<p,s,e>), D-7 
/BOTTOM qualifier, CD-—112 
/BRANCH qualifier, CD-17, CD-30, CD-125, 
CD-184, CD-258 


Breakpoint 
canceling, 3-15, CD-17 
defined, 3-8 


delayed triggering of, 3-13, CD-125 
displaying, CD-—207 
DO clause, 3-13 
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Breakpoint (cont’d) 
exception, 9-10, CD-124 
in tasking (multithread) program, 12-24 
on activation (multiprocess program), 10-12 
on task event, 12—27 
on termination (image exit), 10-12 
on vector instruction, 11-3 
predefined, 9-9 
predefined, tasking (multithread) program, 
12-29 
setting, 3-8, CD-124 
source display at, 6-7 
WHEN clause, 3-13 
with DECwindows, 1-23 
/BRIEF qualifier, CD-—218, CD-230 
Built-in symbol, D-2 
/BYTE qualifier, CD-59, CD-82 
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/CALLABLE_EDT qualifier, CD-134 
/CALLABLE_LSEDIT qualifier, CD-134 
/CALLABLE_TPU qualifier, CD-134 
CALL command, 8-10, CD-10 
and ASTs, 9-16, CD-10 
multiprocess program, 10-5 
vectorized program, 11-22 
with DECwindows, 1-8 
%CALLER_TASK, 12-14 
Call frame 
field and buttons in main window 
with DECwindows, 1-9, 1-21, 1-26 
/CALL qualifier, CD-17, CD-30, CD-125, 
CD-184, CD—258 
/CALLS qualifier, 12-27, CD-152, CD—246 
Call stack 
See also Scope 
displaying, 2~13, 9-12, CD-209, CD-—241 
with DECwindows, 1-23 
used to control instruction display, 7-9, 
CD-166 
with DECwindows, 1-9, 1-21 
used to control source display, 7-6, CD-166 
with DECwindows, 1-9, 1-21 
used to control symbol search, 5-10, CD-166 
with DECwindows, 1-9, 1-26 
CANCEL ALL command, CD-15 
CANCEL BREAK command, 3-15, CD-17 
CANCEL DISPLAY command, 7-12, CD-20 
CANCEL IMAGE command, 5-14, CD-22 
CANCEL MODE command, CD-23 
CANCEL MODULE command, 5-7, CD-24 
CANCEL RADIX command, 4-11, CD-—26 
CANCEL SCOPE command, 5-11, CD-27 
CANCEL SOURCE command, 6-3, CD—28 
CANCEL TRACE command, 3-15, CD-30 


CANCEL TYPE/OVERRIDE command, 4-24, 
CD-33 
CANCEL WATCH command, 3-15, CD-34 
CANCEL WINDOW command, 7-14, CD-35 
Case sensitivity, 9~9 
Catchall handler, 9-13 
Circumflex (*), 4-8, 4-13, D-5 
/CLEAR qualifier, CD—67 
Code 
see Instruction, Address expression 
Colon (:) 
range delimiter, 4—16, 11-4, 11-6, 11-7, CD-81 
Command format 
debugger, CD-3 
Command interface 
COMMAND box, DECwindows, 1-19, 1-27 
debugger, 2-1 
with DECwindows, 1-27, 1-33 
debugger commands disabled in DECwindows, 
1-27 
Command procedure 
See also Initialization file, debugger 
debugger, 8-1 
default directory for, CD-123, CD-206 
displaying commands in, CD-155 
exiting, CD-—7, CD-90, CD-106 
invoking, CD-7 
log file as, 8-5 
passing parameters to, 8-2, CD-44 
recreating displays with, 7—21, CD-97 
with DECwindows, 1-28 
/COMMAND qualifier, 8-6, CD—47 
Comment 
format, CD-4 
Compiler 
compiler generated type, 4—4 
/DEBUG qualifier, 5-2, 6-1 
with DECwindows, 1-3 
/LIST qualifier, 6-1 
/NOOPTIMIZE qualifier, 5-2, 9-1 
with DECwindows, 1-3 
Condition handler 
debugging, 9-10 
/CONDITION_VALUE qualifier, CD-—77, CD-—82 
CONNECT command, 10—4, 10-13, CD-36 
Contents-of operator, 4—6, 4-19, D-7 
CONTROL_C_INTERCEPTION package, 12-32 
Ctrl/C, 2-7, 10-4, 10-9, CD-38 
Ctrl/W, CD-40, CD-69 
Ctrl/Y, 2-7, 3-8, 3-4, 10-12, CD-41 
interrupting tasks in debugger, 12-32 
with DECwindows, 1-31 
Ctrl/Z, 3-4, CD-40 
%CURDISP, C-6 
%CURLOC, 4-8, 4-13, D-5 
Current 
display, 7-3, 7-18, CD-117, CD—238 


Current (cont’d) 
entity, 4-8, 4-13, 4-19, D-5 
with DECwindows, 1-9 
image, 5—14, CD-138, CD-217 
language, 4-10, CD-141, CD-220 
location, 2—10, 6—4, 6-5, 7~6, 7-9 
with DECwindows, 1-21 
radix, 4-10, CD-164, CD-234 
scope, 5-11, CD-166, CD-235 
type, 4-23, CD-191, CD-—252 
value, 4—6, D-5 
Current entity 
field and buttons in main window 
with DECwindows, 1-9 
/CURRENT qualifier, 5-11, CD-166 
%CURRENT_SCOPE_ENTRY, D-10 
%CURSCROLL, C-6 
%CURVAL, 4-6, D-5 


D 


Data type 
See Type 
/DATE_TIME qualifier, CD-59, CD-—82 
DBG$DECW$DISPLAY 
with DECwindows, 1-32, 1-33, 1-34, D-1 
DBG$INIT, 8—4, D-1 
DBG$INPUT, 9-5, D-1 
with DECwindows, 1-33 
DBG$OUTPUT, 9-5, D-1 
with DECwindows, 1-33 
DBG$PROCESS, 2-6, 10-1, 10~9, D-1 
with DECwindows, 1-3, 1-29 
Deadlock 
debugging deadlocks, 12-30 
DEBUG command, 3-3, 10-12, CD-41 
with DECwindows, 1-31 
Debugger 
command interface, 2—1 
with DECwindows, 1-27, 1-33 
DECwindows interface, 1-1 
displaying command interface on other 
terminal, 9-5 
with DECwindows, 1-33 
displaying DECwindows interface on other 
workstation, 1-32 
invoking from DECwindows FileView window, 
1-31 
invoking over DECnet link, 3-1 
Debugger command 
dictionary, CD-6 
format, CD-3 
repeating, CD-99, CD-109, CD-268 
summary, 2-25 
with DECwindows, 1-27, 1-33 
Debugging configuration 
See also Debugger 
default, 2-6, 10-9 
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Debugging configuration 
default (cont’d) 
with DECwindows, 1-3 
multiprocess, 10-1, 10-9 
with DECwindows, 1-29 
/DEBUG qualifier, 3-1, 5-2, 5-4, 6-1 
shareable image, 5-12 
with DECwindows, 1-3 
Debug symbol table 
See DST 
%DEC, 4-11, D-5 
/DECIMAL qualifier, 4-11, CD-77, CD-—79, CD-82 
DECLARE command, 8-2, CD-44 
DECnet 
debugging over, 3-1 
DECthreads 
See Tasking (multithread) program 
DECwindows 
debugger interface, 1~1 . 
debugging DECwindows application, 1-32 
%DECWINDOWS, D-5 
DECwindows interface 
debugger, 1-1 
displaying on other workstation, 1-32 
disabled debugger commands, 1-27 
/DEFAULT qualifier, CD-82 
DEFINE command, 8-6, Ci)-47 
displaying default qualifiers for, CD-211 
setting default qualifiers for, CD-133 
/DEFINED qualifier, CD-—243 
DEFINE/KEY command, 8-8, CD-49 
DEFINE/PROCESS_GROUP command, 10-12, 
CD-52 
DELETE command, 8-6, CD-54 
DELETE/KEY command, 8-8, CD-56 
Deposit 
DEPOSIT command, 4-3, CD-58 
instruction, 4—21, 11-12 
with DECwindows, 1-24 
into address, 4—23 
with DECwindows, 1-25 
into register, 4—22, 11-4 
with DECwindows, 1-25 
into variable, 4—3, 4-14 
with DECwindows, 1-24 
into vector register, 11-4 
vector instruction, 11-12 
DEPOSIT command, 4-3, CD-58 
%DESCR, CD-10 
/DIRECTORY qualifier, CD-218 
/DIRECT qualifier, CD-243 
DISABLE AST command, 9-16, CD-64 
Display, debugger, screen mode 
See also Source display, Instruction, Window 
attribute, 7-3, 7-18, CD-117, CD-238 
canceling, 7-12, CD-20 
contracting, 7-12, CD-94 
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Display, debugger, screen mode (cont'd) 

creating, 7-12, CD-65 

current, 7-3, 7-18, CD—117 

default configuration, 7—2, 7-4 

defined, 7—2 

DO display, 7-15, 11-23 

expanding, 7-12, CD-94 

extracting, 7~21, CD-97 

hiding, 7-11, CD-67 

identifying, 7~12, CD-212 

instruction display (INST), 7-7, 7-16 

kind, 7-8, 7-14, C-1 

list, 7-3, CD-212, C-6 

moving, 7-12, CD-104 

output display (OUT), 7-6, 7-16 

pasteboard, 7~3, CD-—70 

predefined, 7-4, C-3 

process specific, 10-14 

prompt display (PROMPT), 7-7 

register display (REG), 7-9, 7-17, 11-23 

removing, 7-12, CD-69 

saving, 7-21, CD-110 

scrolling, 7~11, CD-112 

selecting, 7-18, CD~117 

showing, 7-12, CD-65 

window, 7-2, 7-13, C—7 
DISPLAY command, 7—11, 7-12, CD-65 
DO clause 

example, 3-13 

exiting, CD-90, CD-106 

format, CD-4 
DO command, 10-5, 10-6, CD-72 
DO display, 7-15, C-1 
/DOWN qualifier, CD-94, CD-104, CD-112 
DST (debug symbol table) 

creating, 5-4 

shareable image, 5-13 

source line correlation, 6-1 
Dynamic mode, CD-148 

image setting, 5-14 

module setting, 5-7 

with DECwindows, 1-26 

Dynamic process setting, 10-7, CD-158 
Dynamic prompt setting, 10-2, CD-161 
/DYNAMIC qualifier, CD-67, CD-158, CD-—230 
/D_FLOAT qualifier, CD-59, CD-82 


E 


/ECHO qualifier, CD-50 
EDIT command, CD-74 
/EDIT qualifier, CD-28, CD-172, CD-—239 
ENABLE AST command, 9~16, CD—76 
/ERROR qualifier, 7-19, CD-117 
Evaluate 

%CURVAL built-in symbol, 4-6, CD-78, D-5 

expression, 4-3, 4-5, CD—77 

with DECwindows, 1-25 


Evaluate (cont'd) 
memory address, 4—12, CD~79 
with DECwindows, 1-24 
task, 12-—12 
EVALUATE/ADDRESS command, 3-12, 3-17, 
4-12, CD79 
EVALUATE command, 4~5, CD-77 
Event 
breakpoint or tracepoint on, 3-14 
tasking (multithread) program, 12-27 
Event facility, 12-27, CD-136, CD-215 
Eventpoint 
See Breakpoint, Tracepoint, Watchpoint 
/EVENT qualifier, 3-14, 12—27, 12-29, CD-17, 
CD-30, CD-125, CD-184 
Examine 
address, 4~-23 
with DECwindows, 1-25 
EXAMINE command, 4—2, CD-81 
instruction, 4-19, 11-9 
with DECwindows, 1-24 
register, 4—22, 11-4 
with DECwindows, 1-25 
task, 12-12, 12-26 
using vector mask, 11-13 
variable, 4—2, 4-14 
with DECwindows, 1~24 
vector address expression, 11-16 
vector instruction, 11~9 
vector register, 11-4 
Examine button 
with DECwindows, 1-9 
EXAMINE command, 4-2, CD-81 
EXAMINE/INSTRUCTION command, 4-19, 7-9, 
C-5 
EXAMINE/OPERANDS command, 4-19, 11-9 
EXAMINE/SOURCE command, 6-4, 7-6, C-4 
Exception 
See also Vector exception 
debugging, 9-10 
Exception breakpoint or tracepoint 
canceling, 9-11, CD-17, CD-30 
qualifying, 9-15, D~9 
resuming execution at, 9~—11 
setting, 9-10, CD-125, CD-184 
Exception handler 
debugger as, 3-20 
debugging, 9-10 
/EXCEPTION qualifier, 9-10, CD-17, CD-30, 
CD-125, CD-184, CD-258 
Exclamation point (!) 
comment delimiter, CD-—4 
log file, 8-5 
%EXC_FACILITY, 9-15, D~9 
%EXC_NAME, 9-15, D-9 
%EXC_NUMBER, 9-15, D-9 


%EXC_SEVERITY, 9-15, D-9 
Execution 
as controlled by debugger, 3—20 
discrepancies caused by debugger, 3-21 
interrupting with Ctrl/C, 2-7 
interrupting with Ctrl/Y, 3-3 
with DECwindows, 1-31 
interrupting with Stop button 
with DECwindows, 1-9, 1-20 
monitoring with SHOW CALLS command, 
2-13, CD-209 
monitoring with tracepoint, 3-9, CD-183 
with DECwindows, 1-23 
multiprocess program, 10-5, CD-149 
resuming after exception break, 9-11 
starting or resuming with CALL command, 
8-10, 11-22, CD-10 
starting or resuming with GO command, 2-12, 
CD-100 
with DECwindows, 1-23 
starting or resuming with STEP command, 
3-6, CD-258 
with DECwindows, 1-23 
suspending with breakpoint, 3-8, CD-124 
with DECwindows, 1-23 
suspending with exception breakpoint, 9-10, 
CD-125 
suspending with watchpoint, 3-15, 10-15, 
CD-196 
with DECwindows, 1-24 
vectorized program, 11-2 
$EXIT, 9-15 
EXIT command, 3-4, 9-15, CD—90 
multiprocess program, 10-8, 10-9 
with DECwindows, 1-20 
Exit handler 
debugging, 9~15, CD-90 
executing, 3-4, CD-90 
with DECwindows, 1-20 
execution sequence of, 9-15 
identifying, 9-16, CD~216 
EXITLOOP command, 8-10, CD-93 
/EXIT qualifier, CD-74 
EXPAND command, 7-12, CD—-94 


Expression 


See Address expression, Language expression 
EXTRACT command, 7-21, CD-97 


F 


File 
See Command procedure, Log file, Initialization 
file, Source file 
Final handler, 9-13 
/FLOAT qualifier, CD-59, CD-—82 
/FMASK qualifier, 11-13, CD-84 
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FOR command, 8—9, CD-99 
%FP, 4-22, D-3 
/FULL qualifier, CD—230, CD-246 


G 


General register 
See also Register 
/GENERATE qualifier, CD-67 
Global section watchpoint, 10-15 
Global symbol 
See Symbol 
Global symbol table 
See GST 
Go button 
with DECwindows, 1-9 
GO command, 2-12, CD-100 
multiprocess program, 10-5 
with DECwindows, 1-23 
GST (global symbol table) 
creating, 5-4 
shareable image, 5-13 
/G_FLOAT qualifier, CD-—59, CD-82 


H 


Handler 
condition, 9-13 
Help 
online, 2-7, CD-102 
for debugger messages, 2—7, CD-5 
with DECwindows, 1-18 
HELP command, 2-7, CD-102 
%HEX, 4-11, D-5 
' [HEXADECIMAL qualifier, 4-11, CD-77, CD-79, 
CD-83 
/HIDE qualifier, CD-67 
/HOLD qualifier, 10~3, 10-6, 12-15, 12-19, 
12~—23, CD-158, CD-179, CD-230, CD-—247 
Hyphen (-) 
line-continuation character, CD—4 
/H_FLOAT qualifier, CD-—59, CD-83 


Identifier 

search string, 6—6 
ADENTIFIER qualifier, 6-6, CD-115 
IF command, 8-9, CD-103 
/AIF_STATE qualifier, 8-8, CD-50 
Image 

See also Shareable image 

privileged, securing, 5-5 

shareable, debugging, 5-12 

with DECwindows, 1-28 

Indirection operator 

See Contents-of operator 
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Initialization 
debugging session, 3-1, 9-7 
with DECwindows, 1-5 
Initialization code, 9-9 
with DECwindows, 1-5 
Initialization file 
See also Command procedure, debugger 
debugger, 8—4, D-1 
with DECwindows, 1-28 
Input, debugger 
DBG$DECW$DISPLAY 
with DECwindows, 1-32, D-1 
DBG$INPUT, 9-5, D-1 
with DECwindows, 1-33 
/INPUT qualifier, 7-19, CD-117, CD-164, 
CD-256 
Instruction 
See also Vector instruction 
depositing, 4-18, 4-21 
with DECwindows, 1-24 
display (INST), 4-18, 7-7, 10-14, C-5 
for routine on call stack, 7—9, CD-166 
with DECwindows, 1-9, 1-11, 1-21 
display kind, 7-16, C-—1 
EXAMINE/INSTRUCTION command, 4-19, 
7-9, C-5 
EXAMINE/OPERANDS command, 4-19 
examining, 4—18, 4-19, 7-7 
with DECwindows, 1-21, 1-24 
operand, 4-19, CD-83, CD-150 
optimized code, 7—7, 9-1 
with DECwindows, 1-11, 1-21 
selecting from DECwindows window, 1-22 
SET SCOPE/CURRENT command, 7-9, 
CD-166 
window (INST), DECwindows, 1-11, 1-21 
/INSTRUCTION qualifier, 7—9, 7-19, CD-17, 
CD-30, CD-60, CD-83, CD-118, CD-126, 
CD-185, CD—258 
%INST_SCOPE, 7-16, C-5 
Integer type, 4-14, 4-23, 4-25 
Interface 
See Command interface, DECwindows interface 
Interrupt 
debugging session, 3-4 
execution of command, 2-7, CD-38 
with DECwindows, 1-20 
execution of program, 2-7, 3-3, 10-5, 10-9, 
10-12, CD-36, CD-38, CD41, CD-149 
with DECwindows, 1-20 
AINTO qualifier, CD-126, CD-185, CD-196, 
CD-—258 
Invoking 
debugger, 2~—4, 2-6, 3-1, 10-1, 10-12, CD-41 
with DECwindows, 1-2, 1-4, 1-31 


J 


/JSB qualifier, 3-12, CD-126, CD-185, CD—258 


K 


Key definition 

creating, 8-8, CD—49 

debugger predefined, B-1 

with DECwindows, 1-29 

debugger predefined, multiprocess, 10-14 

deleting, 8-8, CD-56 

displaying, 8-8, CD~218 
Keypad mode, 8-7, CD-49, CD-149, CD-—218, B-1 
Key state, 8-8, CD-49, CD-218, B-1 


L 


%LABEL, 3-10, D-7 
Language 
current, 4~—10, CD-141 
identifying, CD~—220 
multilanguage program, 9-6 
with DECwindows, 1-28 
setting, 4-10, CD-141 
support by debugger, E-1 
with DECwindows, 1-2 
Language expression 
compared to address expression, 4-7 
with DECwindows, 1-22 
DEPOSIT command, 4-3, CD-58 
EVALUATE command, 4—5, CD-77 
evaluating, 4—5 
with DECwindows, 1-25 
FOR command, 8-9, CD-99 
IF command, 8-9, CD-103 
REPEAT command, 8~—10, CD—109 
WHEN clause, 3-13 
WHILE command, 8-10, CD-268 
Language-Sensitive Editor, CD—74 
Last-chance handler, 9-13 
LAT terminal 
debugging using two, 9-6 
/LEFT qualifier, CD—-94, CD-104, CD-112 
Lexical function 
See Built-in symbol 
LIB$INITIALIZE, 9-9 
%LINE, D—7 
EXAMINE command, 4-19 
EXAMINE/SOURCE command, 6—4 
GO command, CD-100 
SET BREAK command, 3-10 
SET TRACE command, 3-10 
STEP command, 3-6 
Line mode, CD-149 
Line number 
See also LINE 


Line number (cont'd) 
selecting from DECwindows window, 1-22 
source display, 6~1, 6-3, 6-4 
with DECwindows, 1-10 
traceback information, 2-13, 5-3 
treated as symbol, 5-9 
/LINE qualifier, 3-12, CD-18, CD-31, CD-83, 
CD-127, CD-185, CD-—259 
LINK command, 3-1, 5-4, 6-1 
shareable image, 5-12 
with DECwindows, 1-3 
/LIST qualifier, 6—1 
/LOCAL qualifier, 8-6, CD-47, CD-54, CD—243 
Local symbol 
See Symbol 
/LOCK_STATE qualifier, CD-50 
Log file 
as command procedure, 8-5 
debugger, 8-5, CD-155 
with DECwindows, 1-27 
name of, 8-5, CD-143, CD-221 
Logical name 
debugger, D-1 
Logical predecessor, 4-8, 4-13, 4-19, D-5 
with DECwindows, 1-9 
Logical successor, 4—8, 4-13, 4-19, D-5 
with DECwindows, 1-9 
/LOG qualifier, CD-—50, CD—-56 
/LONGWORD qualifier, CD-60, CD-83 


M 


Margin 
source display, 6-8, CD-144, CD-222 
/MARK_CHANGE qualifier, CD-67 
Mask 
EXAMINE/FMASK command, 11-13 
EXAMINE/TMASK command, 11-13 
masked vector operation, 11-5, 11-9, 11-13 
register, VMR, 11-5, 11-9, 11-13 
Memory 
effect of debugger, 3-21 
Message 
debugger, 2—7, CD-—5 
with DECwindows, 1-20 
MicroVAX 
See Workstation 
Mode 
CANCEL MODE command, CD-23 
SET MODE [NOJDYNAMIC command, 5-7, 
5—14, CD-148 
SET MODE [NO]G_FLOAT command, CD-148 
SET MODE [NOJINTERRUPT command, 
CD-149 
SET MODE [NOJKEYPAD command, 8-7, 
CD-—149 
SET MODE [NO]LINE command, CD-149 
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Mode (cont'd) 
SET MODE [NOJOPERANDS command, 4-19, 
CD-150 
SET MODE [NO]SCREEN command, 7-1, 
CD-150 © 
SET MODE [NO]SCROLL command, CD-150 
SET MODE [NO]SEPARATE command, 9-5, 
CD-150 
with DECwindows, 1-33 
SET MODE [NO]JSYMBOLIC command, 4-13, 
CD-151 
SHOW MODE, CD-224 
/MODIFY qualifier, CD-127, CD-185 
Module, 2-5 
See also Shareable image 
canceling, 5-7, CD-24 
information about, 5-7, CD—225 
setting, 5-6, CD-152 
with DECwindows, 1-26 
traceback information, 5-3 
with DECwindows, 1-3 
/MODULE qualifier, CD-—28, CD-167, CD-172 
MOVE command, 7-12, CD-104 
Multilanguage program 
debugging, 9-6 
with DECwindows, 1-28 
Multiprocess program 
CALL command, CD-10 
CONNECT command, 10-4, 10-13, CD-36 
controlling execution, 10-5 
DBG$PROCESS, 10-9 
debugging, 10-1 
with DECwindows, 1-9, 1-29 
DEFINE/PROCESS_GROUP command, CD-52 
DO command, 10-5, CD—72 
EXIT command, 10-8, 10-9, CD—90 
with DECwindows, 1-20 
global section watchpoint, 10-15 
GO command, 10-5, CD-100 
QUIT command, 10-8, 10-9, CD-106 
with DECwindows, 1-20 
screen mode features, 10-14 
SET MODE [NO]JINTERRUPT command, ~ 
10-6, CD-149 
SET PROCESS command, 10-6, 10-7, CD-157 
SHOW PROCESS command, 10-2, CD-229 
specifying processes, 10-11 
STEP command, 10—5, CD—258 
system requirements, 10-16 
with DECwindows, 1-9, 1-29 
Multithread program 
See Tasking (multithread) program 
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%NAME, D-4 
Network 
debugging over, 3-1 
%NEXTDISP, C-6 
%NEXTINST, C-6 
%NEXTLOC, 4—8, 4-13, D-5 
Next location 
See Logical successor 
%NEXTOUTPUT, C-6 
/NEXT qualifier, 6-6, CD-115 
%NEXTSCROLL, C-6 
%NEXTSOURCE, C-6 
%NEXT_PROCESS, 10-11 
%NEXT_SCOPE_ENTRY, D-10 
J%NEXT_TASK, 12-14 
Nonstatic variable, 3-17, 4-1 
with DECwindows, 1-24 
/NOOPTIMIZE qualifier, 2-5, 5-2, 9-1 
with DECwindows, 1-3 
NOP (No Operation) instruction, 4—21 


O 


Object module, 5-3, 6-1 
%OCT, 4-11, D-5 
/OCTAL qualifier, 4-11, CD-77, CD-79, CD-83 
/OCTAWORD qualifier, CD-—60, CD-83 
Operand 
instruction, 4-19, CD-83, CD-150 
vector instruction, 11-5, 11-9 
/OPERANDS qualifier, 4-19, 11-9, CD-83, 
CD-150 
Operator 
address expression, D-6 
language expression, E-1 
Optimization 
effect on debugging, 2-5, 5-2, 7-7, 9-1 
with DECwindows, 1-8, 1-10, 1-11 
/OPTIMIZE qualifier, 2—5, 5-2, 9-1 
with DECwindows, 1-3 
/OPTIONS qualifier, 5-12 
Output 
configuration, displaying, 8-2, 8-5, CD-228 
configuration, setting, 8-2, 8-5, CD-155 
debugger, DBG$DECW$DISPLAY 
with DECwindows, 1-32, D-1 
debugger, DBG$OUTPUT, 9~5, D-1 
with DECwindows, 1-33 
display (OUT), 7-6, C-4 
with DECwindows, 1-10 
display kind, 7-16, C—1 
window (OUT), DECwindows, 1-10 
/OUTPUT qualifier, 7~19, CD-118, CD-~164, 
CD-256 


/OVER qualifier, CD-127, CD-186, CD-197, 
CD-259 

/OVERRIDE qualifier, 4—24, CD-26, CD-33, 
CD-164, CD-192, CD-234, CD-252 

Override type, 4-24 


p 


/PACKED qualifier, CD-~60, CD-84 
%PAGE, C-6 
/PAGE qualifier, 7~—22, CD-181 
Parameter 
debugger command procedure, 8~2, CD—44 
%PARCNT, 8-2, D-4 
Pasteboard, 7~3 
Path name 
abbreviating, 5~9 
numeric, 5-10 
relation to symbol, 5-9 
with DECwindows, 1-10 
syntax, 5-9 
to specify scope, 3~11, 5-8, 5-9 
with DECwindows, 1-26 
%PC 
See PC 
PC (program counter) 
built-in symbol (%PC), 4-22, D-3 
content of, 2-11, 4—19 
EXAMINE/INSTRUCTION command, 7-9, 
7-16 
EXAMINE/OPERANDS command, 4-19, 11-9 
EXAMINE/SOURCE command, 6-4, 7-6, 7-18, 
7-20 
examining, 4—19, 11-9 
with DECwindows, 1-24 
scope, 5-8 
SHOW CALLS display, 2-13, CD-209 
Period (.) 
contents-of operator, 4—6, 4-19, D-7 
current entity, 4—8, 4-13, D-5 
Pointer type, 4-18 
/POP qualifier, CD-67, CD~162 
Pop-up menu 
with DECwindows, 1-12 
Predecessor 
See Logical predecessor 
/PREDEFINED qualifier, CD-15, CD-18, CD-31, 
CD-207, CD-250 
Previous location 
See Logical predecessor 
%PREVIOUS_PROCESS, 10-11 
%PREVIOUS_SCOPE_ENTRY, D-10 
%PREVIOUS_TASK, 12-14 
%PREVLOC, 4-8, 4-13, D-5 
Primary handler, 3-20, 9-13 
Priority 
of task or thread, 12-15, 12-19 


/PRIORITY qualifier, CD-179, CD-247 
Privilege 
allocate terminal, 9-6 
Process 
activation tracepoint, predefined, 10-12 
connecting debugger to, 10-4, 10-13, CD-36 
multiprocess debugging, 10~1 
with DECwindows, 1-9, 1-29 
termination tracepoint, predefined, 10-12 
/PROCESS qualifier, 10-5, 10-14, CD-68, CD-—72 
/PROCESS_GROUP qualifier, 10-12, CD-52 
%PROCESS_NAME, 10-11 
%PROCESS_NUMBER, 10-11 
%PROCESS_PID, 10-11 
Program 
display kind, 7-18, C—1 
Program counter 
See PC 
/PROGRAM qualifier, 7-19, CD-118 
Prompt 
COMMAND box, DECwindows, 1-27 
debugger (DBG>), 2-6, 10-2, CD-161 
with DECwindows, 1-27, 1-33 
display (PROMPT), 7-7, C4 
multiprocess program, 10-2 
/PROMPT qualifier, 7-20, CD-118 
Protection 
debugging with two terminals, 9-6 
of terminal, 9-6 
%PSL, 4-22, D-3 
PSL (processor status longword), 4-22 
/PSL qualifier, CD-84 
/PSW qualifier, CD-84 
/PUSH qualifier, CD-69 


Q 


/QUADWORD qualifier, 11-6, 11-7, CD-60, 
CD-84 
QUIT command, 3—4, CD-106 
multiprocess program, 10-8, 10-9 
with DECwindows, 1-20 
Quotation mark (") 
ASCII string delimiter, 4—15 
instruction delimiter, 4-21 


R 
Radix 
canceling, CD-26 
conversion, 4-10, D-5 
current, 4-10, CD-164 
displaying, CD-234 
multilanguage program, 9-8 
specifying, 4-10, CD-164 
Range 
colon (:), 4-16, 11-4, 11-6, 11-7, CD-81 
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Real type, 4-14 
Record 
source line correlation, 6—1 
Record type, 4-17 
%REF, CD-10 
/REFRESH qualifier, CD-—-69 
Register 
See also Vector register 
built-in symbol, 4—22, D-3 
depositing into, 4—22 
with DECwindows, 1-25 
display (REG), 7-9, C-5 
with DECwindows, 1-12 
display kind, 7~17, C—1 
examining, 4—22 
with DECwindows, 1-25 
PC 
See PC 
PSL, 4-22 
symbol, D-3 
symbolizing, 4—13, CD-263 
with DECwindows, 1-25 
variable, 3-17, 4—1 
with DECwindows, 1-24 
watchpoint, 3-17 
window (REG), DECwindows, 1-12 
/RELATED qualifier, CD-—-24, CD-152, CD-225 
/REMOVE qualifier, CD-69 
REPEAT command, 8-10, CD-—109 
/RESTORE qualifier, CD-179 
Return key 
logical successor, 4—8, 4-138, D—5 
/RETURN qualifier, CD-127, CD-186, CD-—259 
/RIGHT qualifier, CD-94, CD-104, CD-112 
Routine 
calling, 8-10, 11-22, CD-10 
call stack, 2-13, 7-6, 7-9, CD-166, CD—209 
with DECwindows, 1-21, 1-23, 1-26 
displaying instructions for, on call stack, 7-9, 
CD-166 
with DECwindows, 1-21 
displaying source code for, on call stack, 7-6, 
CD-166 
with DECwindows, 1-21 
EXAMINE/SOURCE command, 6-4 
multiple invocations of, 5-10, CD-166 
with DECwindows, 1-26 
selecting from DECwindows window, 1-22 
SET BREAK command, 3-10 
SET SCOPE command, CD-166 
SET TRACE command, 3-10 
SHOW CALLS command, 2-13 
traceback information, 5-3 
with DECwindows, 1-23 
RST (run-time symbol table), 5-6 
and symbol search, 5-8 
deleting symbol records in, 5-7, CD-24 
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RST (run-time symbol table) (cont’d) 
displaying modules in, 5~7, CD-225 
displaying symbols in, 5-9, CD—243 
inserting symbol records in, 5-6, CD-152 
shareable image, 5-13 
‘with DECwindows, 1-26 

RUN command, 3-1, 3-3, 5-4 
See also Execution 
shareable image, 5-13 
with DECwindows, 1-4 

Run-time symbol table 
See RST 


S 


SAVE command, 7—21, CD~110 
/SAVE_VECTOR_STATE qualifier, 11-22, CD-11 
Scalar type, 4-14 
Scope 
built-in symbol, 7—4, 7-7, 7-16, 7-18, C-3, 
C-5, D-10 
canceling, 5-11, CD-27 
current, 5-11, CD-166 
default, 5-8, CD-27, CD-167, CD-235 
with DECwindows, 1-26 
displaying, 5-11, CD~235 
for instruction display, 7-9, CD-166 
with DECwindows, 1-9, 1-21 
for source display, 7-6, CD-166 
with DECwindows, 1-9, 1-21 
for symbol search, 3-11, 5—8, 5-11, CD-27, 
CD-166, CD-—235 
with DECwindows, 1-9, 1-26 
PC, 5-8 
relation to call stack, 5-10, 5-11, 7—6, 7-9, 
CD-166 
with DECwindows, 1-9, 1-21, 1-26 
SEARCH command, 6-6, CD-114 
search list, 5-8, 5-11, CD-27, CD-166, 
CD-235 
with DECwindows, 1-9, 1-26 
SET SCOPE command, 5-11, 7-6, 7-9, 
CD-166 
setting, 5-11, CD—166 
with DECwindows, 1-26 
specifying with path name, 5-9 
TYPE command, 6—4, CD-—266 
vector register, 11-1 
Screen display 
See Display, debugger, screen mode 
Screen management 
debugging DECwindows application, 1-32 
debugging screen-oriented program, 9-5 
with DECwindows, 1-33 
Screen mode, 7-1, CD-150 
multiprocess program, 10-14 
summary reference information, C-—1 


Screen-oriented program 
debugging, 9—5 
with DECwindows, 1-32, 1-33 
Screen size 
displaying, 7-22, CD-—249 
%PAGE, 2 WIDTH symbols, C—6 
setting, 7-22, CD-181 
/SCREEN_LAYOUT qualifier, CD-97 
SCROLL command, 7-11, CD-112 
Scroll mode, CD-—150 
/SCROLL qualifier, 7-20, CD-118 
SEARCH command, 6—6, CD-114 
displaying default qualifiers for, 6—7, CD-237 
setting default qualifiers for, 6-7, CD-170 
Search list 
scope, 5-8, 5-11, CD-166, CD—235 
with DECwindows, 1-9, 1-26 
source file, 6-2, CD—28, CD-172, CD-239 
Security 
image, 5-5 
terminal, 9-6 
SELECT command, 7-18, CD-117 
Semicolon (;) 
command separator, CD—4 
SET ABORT_KEY command, 2-7, CD-121 
SET ATSIGN command, 8-2, CD-123 
SET BREAK command, 3-8, 6—7, 9-10, 11-3, 
12-24, 12-27, CD-124 
SET DEFINE command, 8-6, CD-133 
SET EDITOR command, CD-134 
SET EVENT_FACILITY command, 12-28, 
CD-136 
SET IMAGE command, 5-14, CD-138 
effect on symbol definitions, CD—48 
SET KEY command, 8-9, CD-140 
SET LANGUAGE command, 4-10, CD-141 
SET LOG command, 8-5, CD—143 
SET MARGINS command, 6-8, CD-144 
SET MAX SOURCE_FILES command, 6-3, 
CD-147 
SET MODE command, CD-148 
SET MODE [NO]DYNAMIC command, 5-7, 5-14, 
CD-148 
SET MODE [NO]G_FLOAT command, CD-148 
SET MODE [NOJINTERRUPT command, 10-5, 
CD-149 
SET MODE [NO]KEYPAD command, 8-7, 
CD-149, B—1 
SET MODE [NO]LINE command, CD-149 
SET MODE [NOJOPERANDS command, 4-19, 
CD-150 
SET MODE [NO]SCREEN command, 7-1, 
CD-150 
SET MODE [NO]SCROLL command, CD-150 
SET MODE [NO]SEPARATE command, 9-5, 
CD-150 
with DECwindows, 1-33 


SET MODE [NOJSYMBOLIC command, 4-13, 
CD-151 
SET MODULE command, 5—6, 5-15, CD-—152 
SET OUTPUT command, CD-155 
SET OUTPUT [NO]JLOG command, 8—5, CD-155 
SET OUTPUT [NO]JSCREEN_LOG command, 
8-5, CD—155 
SET OUTPUT [NO]TERMINAL command, 
CD-155 
SET OUTPUT [NO]VERIFY command, 8-2, 
CD-155 
SET PROCESS command, 10-6, 10-7, CD-157 
SET PROMPT command, CD-161 
SET RADIX command, 4-10, 9-8, CD-164 
SET SCOPE command, 5-11, 6-4, 7-6, 7-9, 
CD-166 
SET SEARCH command, 6—7, CD-170 
SET SOURCE command, 6~2, CD-172 
SET STEP command, 3-7, 4-18, 6-7, 11-3, 
CD-175 
SET TASK command, 12-10, 12-22, CD-178 
SET TERMINAL command, 7~—22, CD-181 
SET TRACE command, 3-9, 6—7, 9-10, 11-3, 
12-24, 12-27, CD-183 
SET TYPE command, 4-23, CD-191 
SET TYPE/OVERRIDE command, 4-24, CD-191 
SET VECTOR_MODE command, 11-19, CD-194 
SET WATCH command, 3-15, 6-7, 11-3, CD-196 
SET WINDOW command, 7-14, CD-202 
/SET_STATE qualifier, 8-9, CD-50 
Shareable image 
See also Module 
CANCEL IMAGE command, 5~—14, CD-22 
debugging, 5-12 
with DECwindows, 1-28 
SET BREAK/INTO command, 3~12, CD-128 
SET IMAGE command, 5-14, CD-138 
SET STEP INTO command, 3-8, CD-176 
SET TRACEANTO command, 3-12, CD-186 
SET WATCH command, 3-20 
SHOW IMAGE command, 5-13, CD-217 
STEP/INTO command, CD-259 
/SHAREABLE qualifier, 5-12 
/SHARE qualifier, 3-12, 5-15, CD-128, CD-186, 
CD-225, CD-259 
SHOW ABORT_KEY command, CD-204 
SHOW AST command, 9-16, CD-—205 
SHOW ATSIGN command, 8-2, CD-206 
SHOW BREAK command, 3-9, CD-207 
SHOW CALLS command, 2-13, 3-38, 9-10, 9-16, 
CD-209 
SHOW DEFINE command, 8-6, CD-211 
SHOW DISPLAY command, 7-12, CD-212 
SHOW EDITOR command, CD-214 
SHOW EVENT_FACILITY command, 3-14, 
12-28, CD—215 
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SHOW EXIT_HANDLERS command, 9-16, 
CD--216 
SHOW IMAGE command, 5-18, CD-217 
SHOW KEY command, 8-8, CD-218 
SHOW LANGUAGE command, 4-10, CD-220 
SHOW LOG command, 8-5, CD-221 
SHOW MARGINS command, 6-8, CD-222 
SHOW MAX_SOURCE_FILES command, 6-3, 
CD-223 
SHOW MODE command, CD-224 
SHOW MODULE command, 5-7, 5-15, CD-225 
SHOW OUTPUT command, 8-2, 8-5, CD-228 
SHOW PROCESS command, 10-2, 11-2, CD-229 
SHOW RADIX command, 4-10, CD-234 
SHOW SCOPE command, 5-11, CD—235 
SHOW SEARCH command, 6-7, CD-—237 
SHOW SELECT command, 7-20, CD-238 
SHOW SOURCE command, 6-2, CD-239 
SHOW STACK command, 9-12, CD—241 
SHOW STEP command, 3-7, CD-—242 
SHOW SYMBOL command, 5~9, 12-26, CD-243 
SHOW SYMBOL/DEFINED command, 8-6 
SHOW TASK command, 12-13, 12-15, CD-246 
SHOW TERMINAL command, 7-22, CD-249 
SHOW TRACE command, 3-9, CD-—250 
SHOW TYPE command, 4—24, CD-252 
SHOW VECTOR_MODE command, 11-19, 
CD-—253 
SHOW WATCH command, 3-15, CD-254 
SHOW WINDOW command, 7~14, CD—255 
/SILENT qualifier, 3-13, 12-31, CD-128, CD-187, 
CD-197, CD-—259 
/SIZE qualifier, CD-69 
Slash (/) 
division operator, D-—7 
SMG$ 
debugging screen-oriented program, 9-5 
/SOURCE, 12-26 
Source code 
See Source display 
Source directory 
displaying, 6-2, CD-239 
search list, 6—2, CD-28, CD-172 
Source display, 2—8, 6-1, 7~1 
discrepancies in, 7—4, 9-1 
with DECwindows, 1-10 
display kind, 7-17, C—1 
EXAMINE/SOURCE command, 6—4, 7-6, 7-17, 
C-4 
for routine on call stack, 7-6, CD-166 
with DECwindows, 1-9, 1-10, 1-21 
line-oriented, 6-3 
margins in, 6-8, CD-222 
multiprocess program, 10-14 
not available, 2-10, 2-11, 6-1, 7-4, CD-172, 
C-4 
with DECwindows, 1-10, 1-21 
optimized code, 2-5, 5-2, 7-7, 9-1 
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Source display 
optimized code (cont'd) 
with DECwindows, 1-10 
SEARCH command, 6-6, CD-114 
SET BREAK command, 6-7 
SET SCOPE/CURRENT command, 7-6, 
CD-166 
SET STEP command, 6—7, CD-175 
SET TRACE command, 6-7 
SET WATCH command, 6-7 
SRC, predefined, 7—4, C-3 
with DECwindows, 1-10 
STEP command, 6—7 
TYPE command, 6-3, CD-266 
with DECwindows, 1-9, 1-10, 1-21 
Source file 
See also Source display 
correct version of, CD-172, CD-—239 
defined, 6-2 
file specification, 6-2 
location, 6-2, CD-28, CD-172, CD—239 
maximum number, 6-3, CD-147, CD—223 
not available, 6-2, CD-172 
Source line correlation, 6-1 
/SOURCE qualifier, 6-4, 6-7, 7-6, 7-20, CD-84, 
CD-118, CD-128, CD-187, CD-197, CD—260 
Source window 
See also Source display 
SRC, DECwindows, 1-10, 1-21 
%SOURCE_SCOPE, 7-18, C-3 
%SP, 4-22, D-3 
SPAWN command, 3-4, CD-256 
SRC 
source display, screen mode, 7—4, C—3 
source window, DECwindows, 1-10, 1-21 
SS$_DEBUG condition, D-1 
Stack 
See also Call stack, Call frame, Scope 
variable, 3-17, 4-1 
with DECwindows, 1-24 
/START_POSITION qualifier, CD-134 
State 
of task or thread, 12-15, 12-19 
/STATE qualifier, 8-8, CD-57, CD-140, CD-219, 
CD-247 
/STATIC qualifier, CD-197 
Static variable, 3-17, 4—1 
/STATISTICS qualifier, CD-247 
Step button 
with DECwindows, 1-9 
STEP command, 3-6, 6-7, CD-258 
and instruction-level debugging, 4-18 
displaying default qualifiers for, CD-242 
multiprocess program, 10-5 
setting default qualifiers for, CD-175 
vectorized program, 11-3 
with DECwindows, 1-23 


Stop button 
with DECwindows, 1-9, 1-20 
STOP command, 3—4 
/STRING qualifier, 6-6, CD~115 
String type, 4-15, 4-26 
Successor 
See Logical successor 
/SUFFIX qualifier, 10-14, CD-20, CD-69, CD-94, 
CD-97, CD-104, CD-110, CD-112, CD-119, 
CD~-161, CD-—212 
Symbol 
See also DST, GST, RST, Scope 
ambiguity, resolving, 5—7 
with DECwindows, 1-26 
built-in, C-—5, D-2 
compiler generated type, 4—4 
defining, 8-6, CD-48 
displaying, 5-9, 8-6, CD-48, CD-—243 
with DECwindows, 1-24 
global, 5-4, 5-10 
image setting, 5-14 
label, 3-10, 5-1 
line number, 3-11, 5-1 
local, 5-4 
module setting, 5—6 
with DECwindows, 1-26 
not in symbol table, 5-6, 5-15 
with DECwindows, 1-26 
not unique, 5-9 
with DECwindows, 1-26 
overloaded, 12-26, E—4, E-17 
relation to address expression, 4—4 
with DECwindows, 1-22 
relation to path name, 5-9 
with DECwindows, 1-10 
routine, 3-10, 5-1 
search based on call stack, 5—11, CD-166 
with DECwindows, 1~9, 1-26 
search conventions, 3—11, 5-8, CD-167 
with DECwindows, 1-9, 1-26 
SET SCOPE command, 5-11, CD-166 
shareable image, 5—13 
with DECwindows, 1-28 
show symbol 
with DECwindows, 1-24 
SHOW SYMBOL command, 5~9 
symbolic mode, 4—13, CD-151 
traceback information, 5-3 
universal, 5—4, 5-5, 5-12, 5-15 
variable, 3-15, 4-1, 4~14, 5-1 
vector register, 11-1 
Symbolic mode, 4-13, CD-151 
/SYMBOLIC qualifier, 4-13, CD-84 
Symbolize 
address, 3-12, 4—13, CD-—263 
with DECwindows, 1~25 
register, 4-13, CD-—263 


Symbolize 
register (cont’d) 
with DECwindows, 1-25 
vector register, 11-1 
SYMBOLIZE command, 3-12, 4-13, CD-—263 
Symbol record 
See Symbol 
Symbol table 
See DST, GST, RST 
Synchronization 
debugging vectorized program, 11-19, CD-194, 
CD-253, CD-—264 
delivery of vector exception, 11-19, 11-22 
SET VECTOR_MODE command, 11-19, 
CD-194 
SHOW VECTOR_MODE command, 11-19, 
CD-253 
SYNCHRONIZE VECTOR_MODE command, 
11-19, CD-264 
/SYSTEM qualifier, 3-12, CD-128, CD~187, 
CD-260 
System space 
SET BREAK command, CD-128 
SET STEP command, CD-176 
SET TRACE command, CD-187 
STEP command, CD-—260- 


T 


Task, 12-1 
See also Tasking (multithread) program 


%TASK 
See Task ID . 
Task ID, 12-6, 12~12, 12-14, 12-15, 12-19 
Tasking (multithread) program 
active task, 12-10 
comparison of task and DECthreads 
terminology, 12-2 
controlling and monitoring execution, 12—24 
controlling task switching, 12—23 
deadlock condition, 12-30 
debugging, 12-1 
with DECwindows, 1-28 
environment task, 12-6 
event facility, 12-27 
eventpoints, 12-24 
monitoring events, 12-27 
null task, 12-13 
obtaining information about, 12-15 
obtaining priority of task or thread, 12-15, 
12-19 
predefined breakpoint, 12-29 
sample Ada program for debugging, 12-6 
sample C program for debugging, 12-2 
SET EVENT_FACILITY command, 12-28, 
CD-136 
SET TASK command, 12-22, CD~178 
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Tasking (multithread) program (cont’d) 
setting breakpoint, 12-24 
_ setting priority of task or thread, 12-22, 12-30 
setting time-slice value, 12-23 
setting tracepoint, 12-24 
setting watchpoint, 12-24 
SHOW EVENT_FACILITY command, 12-28, 
CD-215 
SHOW TASK command, 12-15, CD-246 
specifying task body, 12-12 
specifying tasks or threads, 12—10 
stack checking, 12-31 
state of task or thread, 12-15, 12-19 
substate of task or thread, 12-15, 12-19 
task built-in symbols, 12-13 
task event, 12-27 
task ID, 12-6, 12-12, 12-14, 12-15, 12-19 
task object, 12-11 
visible task, 12-10 
/TASK qualifier, 12-12, CD-60, CD-84 
Task state, 12-15, 12-19 
Task substate, 12-15, 12-19 
Task switching, 12~—9, 12-23, 12-26 
$TASK_ BODY, 12-12, 12-25 
/TEMPORARY qualifier, CD-128, CD-187, 
CD-197 
Terminal 
for debugger input/output, separate, 9-5, 
CD-150 
using DECterm window, 1-33 
Terminal emulator 
See also Terminal 
Terminal screen size 
See Screen size 
/TERMINATE qualifier, 8—8, CD-50 
/TERMINATING qualifier, 10-12, CD-18, CD~31, 
CD-129, CD-187 
Termination 
debugging session, 3—4, 10-8, CD-—90, CD-106 
with DECwindows, 1-20 
execution of handlers at, 9-15 
multiprocess program, 10-8, 10-9, 10-12 
Thread 
See Tasking (multithread) program 
/TIME_SLICE qualifier, 12-23, CD-179, CD~—247 
/TMASK qualifier, 11-13, CD-84 
/TOP qualifier, CD-113 
Traceback 
compiler option, 5-3 
link option, 5-4 
SHOW CALLS display, 2-13 
/TRACEBACK qualifier, 3-3, 5-4, 5-5 
shareable image, 5-13 


Tracepoint 
canceling, 3-15, CD-30 
defined, 3-9 


delayed triggering of, 3-138, CD-184 
displaying, CD-—250 
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Tracepoint (cont’d) 
DO clause, 3-13 
exception, 9-10, CD-183 
in tasking (multithread) program, 12-24 
on activation (multiprocess program), 10-12 
on task event, 12-27 
on termination (image exit), 10-12 
on vector instruction, 11-3 
predefined, 10-12 
setting, 3-9, CD-183 
source display at, 6—7 
WHEN clause, 3-13 
with DECwindows, 1-23 
Transfer address, 3-1, 9-7 
Type 
address expression, 4—4, 4-23 
array, 4-16 
ASCII string, 4-15, 4-26 
compiler generated, 4-4, 4-14 
conversion, numeric, 4-7 
current, 4-23, CD-191, CD—252 
displaying, CD-252 
integer, 4-14, 4-25 
override, 4-24, CD-191 
pointer, 4-18 
real, 4-14 
record, 4-17 
scalar, 4-14 
SET TYPE command, 4-23, CD-191 
symbolic address expression, 4—4 
/TYPE qualifier, 4—26, CD-60, CD-85, CD~243 
VAX instruction, 4-18 
vector register, 11-6 
TYPE command, 6-3, 7-6, CD—266 
Type override, 4-24, CD-33, CD-192, CD-252 
/TYPE qualifier, 4-26, CD-60, CD-85, CD—243 


U 


Universal symbol 
See Symbol . 
/UP qualifier, CD-95, CD-105, CD-113 
/USER qualifier, CD-15, CD-~18, CD-31, CD—207, 
CD-250 
/USE_CLAUSE qualifier, CD-244 


V 


%VAL, CD-10 
/VALUE qualifier, 8-6, CD-47 
Variable 
as override type, 4-26 
depositing into, 4-3, 4-14 
with DECwindows, 1-24 
examining, 4-2, 4-14 
with DECwindows, 1-24 
global section, 10-15 
initialized, 4—1 


Variable (cont’d) 
nonstatic, 3-17, 4-1 
with DECwindows, 1~24 
optimized code, 9-1 
register, 3-17, 4-1 
with DECwindows, 1-24 
selecting from DECwindows window, 1-22 
stack local, 3-17, 4—1 
with DECwindows, 1-24 
static, 3-17 
uninitialized, 3-21 
watchpoint, 3-15, 10-15 
with DECwindows, 1-24 
Variable name 
address expression, 4—7 
with DECwindows, 1-22 
DEPOSIT command, 4-3 
EXAMINE command, 4-2 
language expression, 4—6 
selecting from DECwindows window, 1-22 
SET WATCH command, 3-15 
VAX Language-Sensitive Editor, CD-74 
VAXstation 
See Workstation 
VAX Vector Instruction Emulation Facility 
See VVIEF 
%VCR 
See VCR 
VCR (vector count register), 11-4, D-3 
Vector count register 
See VCR 
Vector exception 
delivery of, 11-19, 11-22 
Vector instruction, 11-8 
CANCEL BREAK/VECTOR_INSTRUCTION 
command, 11-3, CD-18 
CANCEL TRACE/VECTOR_INSTRUCTION 
command, 11-3, CD-31 
delivery of vector exception, 11-19, 11-22 
depositing, 11-12 
displaying, 11~8 
EXAMINE/OPERANDS command, 11~9 
examining, 11-9 
masked operation, 11-9, 11-14 
operand, 11-9 
replacing, 11-12 
SET BREAK/VECTOR_INSTRUCTION 
command, 11-3, CD-129 
SET STEP VECTOR_INSTRUCTION command, 
11-3, CD-176 
SET TRACE/VECTOR_INSTRUCTION 
command, 11-3, CD-187 
STEP/VECTOR_INSTRUCTION command, 
11-8, CD-260 
Vectorized program 
CALL/[NO]JSAVE_VECTOR_STATE command, 
11-22, CD-11 


Vectorized program (cont’d) 

controlling and monitoring execution, 11-2 

debugging, 11-1 
with DECwindows, 1-29 

delivery of vector exception, 11~19, 11-22 

depositing into vector register, 11-4, 11-6 

depositing vector instruction, 11-12 

EXAMINE/FMASK command, 11-13 

EXAMINE/OPERANDS command, 11-9, 
CD-83 

EXAMINE/TMASK command, 11-13 

examining vector instruction, 11-9 

examining vector register, 11-4, 11-6 

masked operation, 11-5, 11-9, 11-13 

obtaining information about, 11-2 

setting breakpoint, 11-3 

setting tracepoint, 11-3 

setting watchpoint, 11-3 

SET VECTOR_MODE command, 11-19, 
CD-194 ; 

SHOW PROCESS/FULL command, 11-2 

SHOW VECTOR_MODE command, 11-19, 
CD-253 

specifying vector register, 11-4 

SYNCHRONIZE VECTOR_MODE command, 
11-19, CD~264 

synchronizing scalar and vector processors, 
11-19 

V0 to V15, 11-6 

VCR, 11-4 

VLR, 11-4 

VMR, 11-5, 11-9, 11-13 

with DECwindows, 1-29 

Vector length register 


See VLR 
Vector mask register 


See VMR 
Vector mode 
SET VECTOR_MODE [NO]JSYNCHRONIZED 
command, 11-19 
SYNCHRONIZE VECTOR_MODE command, 
11-19 
Vector register 
See also Register 
built-in symbol, 11-4, D-3 
composite address expression, 11-16 
depositing into, 11-4, 11-6 
display, screen mode, 7-9, 7-15, 11-23 
examining, 11-4, 11-6 
scope, 11-1 
VO to V15, 11-6, D-3 
VCR, 11-4, D-3 
VLR, 11-4, D-3 
VMR, 11-5, 11-9, 11-13, D-3 
watchpoint, 11-3 
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/VECTOR_INSTRUCTION qualifier, 11-3, 
CD-18, CD-31, CD-129, CD-187, CD-—260 
Verify 
SET OUTPUT VERIFY command, CD-155 
Virtual memory address 


See Memory address 
Visible process, 10-2, 10-7 
field and buttons in main window 
with DECwindows, 1-9 
/VISIBLE qualifier, 12-11, CD-158, CD-179, 
CD-—230 
%VISIBLE_PROCESS, 10-11 
%VISIBLE_TASK, 12-10, 12-14 
%VLR 
See VLR 
VLR (vector length register), 11—4, D-3 
%VMR 
See VMR 
VMR (vector mask register), 11-4, 11-5, 11-9, 
~ 11-13, D-3 
VVIEF (VAX Vector Instruction Emulation 
Facility) 
SHOW PROCESS/FULL command, 11-2 


WwW 
/WAIT qualifier, CD-256 
Watchpoint 
aggregate, 3-17, 11-3 
canceling, CD-34 
defined, 3-15 
displaying, CD-254 
effect on execution speed, 3-18 
global section, 10-15 
in tasking (multithread) program, 12-23, 
12-24 
multiprocess program, 10-15 
nonstatic (stack or register) variable, 3-17 
register, 3-17 
setting, 3-15, CD-196 
shareable image, 3-20 
source display at, 6—7 
static variable, 3-17 
vector register, 11-3 
with DECwindows, 1-24 
WHEN clause 
example, 3-13 
format, CD—4 
WHILE command, 8-10, CD—268 
%WIDTH, C-6 
/WIDTH qualifier, 7-22, CD-181 
Window 
See also Display, debugger, screen mode 
attribute, DECwindows, 1-10 
automatic (AUTO), DECwindows, 1-11 
default configuration, DECwindows, 1-4 
for debugger command interface 
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Window 


for debugger command interface (cont’d) 
DECwindows COMMAND box, 1-19, 1-27 
DECwindows DECterm window, 1-33 
VWS window, 9-5,CD-150 — 

instruction (INST), DECwindows, 1-11, 1-21 

output (OUT), DECwindows, 1-10 

predefined, DECwindows, 1-9 

register (REG), DECwindows, 1-12 

screen-mode, creating definition for, 7-14, 
CD-202 

screen-mode, defined, 7-2 

screen-mode, deleting definition of, 7-14, 
CD-35 

screen-mode, identifying, 7-14, CD-—255 

screen-mode, predefined, CD-—255, C-7 

screen-mode, specifying, 7-13 


selecting address expression from, 


DECwindows, 1-22 
source (SRC), DECwindows, 1-10, 1-21 


/WORD qualifier, CD-60, CD-85 
Workstation 


debugger commands for (when using VWS), 
CD-5 

debugger DECwindows interface for, 1—1 

debugging DECwindows application, 1-32 

debugging screen-oriented program 
using separate DECterm window, 1-33 
using separate VWS window, 9-5, CD-150 

popping debugger window (when using VWS), 
CD-162 

separate, for debugger DECwindows interface, 
1-32 

separate debugger terminal-emulator window 
using DECwindows (DECterm), 1-33 
using VWS, 9-5, CD-150 

terminal emulator screen size, 7-22, CD-181 
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